Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your Sendook account. Configure webhook endpoints to listen for specific events and receive POST requests with event data.

Create Webhook

curl -X POST https://api.sendook.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/sendook",
    "events": ["message.received", "message.sent"]
  }'

Create a new webhook endpoint to receive event notifications.

Request Body

url

string

required

The HTTPS URL where webhook events will be sent.Must be a publicly accessible endpoint that can receive POST requests.Example: "https://your-app.com/webhooks/sendook"

events

string[]

required

Array of event types to subscribe to. At least one event is required.Available events:

inbox.created - Inbox was created
inbox.deleted - Inbox was deleted
inbox.updated - Inbox was updated
message.sent - Message was sent from an inbox
message.received - Message was received in an inbox
message.delivered - Message was successfully delivered
message.bounced - Message bounced
message.complained - Recipient marked message as spam
message.rejected - Message was rejected by recipient server

Example: ["message.received", "message.sent"]

Response

string

Unique identifier for the webhook.

organizationId

string

ID of the organization that owns this webhook.

url

string

The webhook endpoint URL.

events

string[]

Array of event types this webhook is subscribed to.

createdAt

string

ISO 8601 timestamp of when the webhook was created.

updatedAt

string

ISO 8601 timestamp of when the webhook was last updated.

List Webhooks

curl https://api.sendook.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve all webhooks configured for your organization.

Response

Returns an array of webhook objects.

string

Unique identifier for the webhook.

organizationId

string

ID of the organization that owns this webhook.

url

string

The webhook endpoint URL.

events

string[]

Array of event types this webhook is subscribed to.

createdAt

string

ISO 8601 timestamp of when the webhook was created.

updatedAt

string

ISO 8601 timestamp of when the webhook was last updated.

Get Webhook

curl https://api.sendook.com/v1/webhooks/webhook_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve a specific webhook by its ID.

Path Parameters

webhookId

string

required

The unique identifier of the webhook to retrieve.

Response

string

Unique identifier for the webhook.

organizationId

string

ID of the organization that owns this webhook.

url

string

The webhook endpoint URL.

events

string[]

Array of event types this webhook is subscribed to.

createdAt

string

ISO 8601 timestamp of when the webhook was created.

updatedAt

string

ISO 8601 timestamp of when the webhook was last updated.

Error Responses

404 Not Found

"Webhook not found" - The webhook doesn’t exist or doesn’t belong to your organization

Test Webhook

curl -X POST https://api.sendook.com/v1/webhooks/webhook_123/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Send a test webhook event to verify your endpoint is configured correctly.

Path Parameters

webhookId

string

required

The unique identifier of the webhook to test.

Response

success

boolean

Returns true if the test event was queued successfully.

Test Event Payload

The test endpoint will send a message.received event with a sample payload:

{
  "event": "message.received",
  "data": {
    "test": "test"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Responses

404 Not Found

"Webhook not found" - The webhook doesn’t exist or doesn’t belong to your organization

Delete Webhook

curl -X DELETE https://api.sendook.com/v1/webhooks/webhook_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete a webhook endpoint.

Path Parameters

webhookId

string

required

The unique identifier of the webhook to delete.

Response

Returns the deleted webhook object.

string

Unique identifier for the deleted webhook.

organizationId

string

ID of the organization that owned this webhook.

url

string

The webhook endpoint URL.

events

string[]

Array of event types the webhook was subscribed to.

createdAt

string

ISO 8601 timestamp of when the webhook was created.

updatedAt

string

ISO 8601 timestamp of when the webhook was last updated.

Error Responses

404 Not Found

"Webhook not found" - The webhook doesn’t exist or doesn’t belong to your organization

List Webhook Attempts

curl https://api.sendook.com/v1/webhooks/webhook_123/attempts \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve all delivery attempts for a specific webhook. This is useful for debugging webhook issues and monitoring delivery success rates.

Path Parameters

webhookId

string

required

The unique identifier of the webhook.

Response

Returns an array of webhook attempt objects.

string

Unique identifier for the webhook attempt.

webhookId

string

ID of the webhook this attempt belongs to.

event

string

The event type that triggered this webhook.

payload

object

The data payload sent to the webhook endpoint.

url

string

The webhook endpoint URL that was called.

statusCode

number

HTTP status code returned by the webhook endpoint.

response

string

Response body returned by the webhook endpoint (if available).

success

boolean

Whether the webhook delivery was successful (status code 2xx).

attemptNumber

number

The attempt number for this delivery (1-5).

createdAt

string

ISO 8601 timestamp of when the attempt was made.

Example Response

[
  {
    "id": "attempt_abc123",
    "webhookId": "webhook_123",
    "event": "message.received",
    "payload": {
      "messageId": "msg_456",
      "inboxId": "inbox_789",
      "from": "[email protected]",
      "subject": "Hello"
    },
    "url": "https://your-app.com/webhooks/email",
    "statusCode": 200,
    "response": "{\"success\":true}",
    "success": true,
    "attemptNumber": 1,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Webhook Event Format

All webhook events are sent as POST requests to your configured URL with the following format:

Headers

Content-Type: application/json
User-Agent: Sendook-Webhook/1.0

Payload Structure

{
  "event": "message.received",
  "data": {
    "id": "msg_123",
    "inboxId": "inbox_456",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello",
    "text": "Message body",
    "html": "<p>Message body</p>",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

event

string

The type of event that occurred.

data

object

The event payload. Structure varies by event type:

Inbox events: Contains inbox object
Message events: Contains message object

timestamp

string

ISO 8601 timestamp of when the event occurred.

Responding to Webhooks

Your endpoint should:

Respond with a 200 status code within 5 seconds
Process the event asynchronously if needed
Return a 200 even if the event is not relevant to your application

Retry Logic

If your endpoint fails or times out, Sendook will retry with exponential backoff:

Attempt 1: Immediate
Attempt 2: After 1 minute
Attempt 3: After 5 minutes
Attempt 4: After 30 minutes
Attempt 5: After 2 hours

After 5 failed attempts, the webhook event is discarded.

Security Best Practices

Use HTTPS

Always use HTTPS URLs for webhook endpoints to ensure data is encrypted in transit.

Validate Source

Verify that webhook requests are coming from Sendook by checking the source IP or implementing signature verification.

Idempotency

Process webhook events idempotently, as you may receive the same event multiple times due to retries.

Overview

Endpoints

Create Webhook

Request Body

Response

List Webhooks

Response

Get Webhook

Path Parameters

Response

Error Responses

Test Webhook

Path Parameters

Response

Test Event Payload

Error Responses

Delete Webhook

Path Parameters

Response

Error Responses

List Webhook Attempts

Path Parameters

Response

Example Response

Webhook Event Format

Headers

Payload Structure

Responding to Webhooks

Retry Logic

Security Best Practices

Build docs developers (and LLMs) love

Overview

Endpoints

​Create Webhook

​Request Body

​Response

​List Webhooks

​Response

​Get Webhook

​Path Parameters

​Response

​Error Responses

​Test Webhook

​Path Parameters

​Response

​Test Event Payload

​Error Responses

​Delete Webhook

​Path Parameters

​Response

​Error Responses

​List Webhook Attempts

​Path Parameters

​Response

​Example Response

​Webhook Event Format

​Headers

​Payload Structure

​Responding to Webhooks

​Retry Logic

​Security Best Practices

Build docs developers (and LLMs) love

Create Webhook

Request Body

Response

List Webhooks

Response

Get Webhook

Path Parameters

Response

Error Responses

Test Webhook

Path Parameters

Response

Test Event Payload

Error Responses

Delete Webhook

Path Parameters

Response

Error Responses

List Webhook Attempts

Path Parameters

Response

Example Response

Webhook Event Format

Headers

Payload Structure

Responding to Webhooks

Retry Logic

Security Best Practices