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"]
  }'

const response = await fetch('https://api.sendook.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/sendook',
    events: ['message.received', 'message.sent']
  })
});

const webhook = await response.json();

import requests

response = requests.post(
    'https://api.sendook.com/v1/webhooks',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://your-app.com/webhooks/sendook',
        'events': ['message.received', 'message.sent']
    }
)

webhook = response.json()

Create a new webhook endpoint to receive event notifications.

Request Body

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"

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.

string

ID of the organization that owns this webhook.

string

The webhook endpoint URL.

string[]

Array of event types this webhook is subscribed to.

string

ISO 8601 timestamp of when the webhook was created.

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"

const response = await fetch('https://api.sendook.com/v1/webhooks', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const webhooks = await response.json();

import requests

response = requests.get(
    'https://api.sendook.com/v1/webhooks',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

webhooks = response.json()

Retrieve all webhooks configured for your organization.

Response

Returns an array of webhook objects.

string

Unique identifier for the webhook.

string

ID of the organization that owns this webhook.

string

The webhook endpoint URL.

string[]

Array of event types this webhook is subscribed to.

string

ISO 8601 timestamp of when the webhook was created.

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"

const response = await fetch('https://api.sendook.com/v1/webhooks/webhook_123', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const webhook = await response.json();

import requests

response = requests.get(
    'https://api.sendook.com/v1/webhooks/webhook_123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

webhook = response.json()

Retrieve a specific webhook by its ID.

Path Parameters

string

required

The unique identifier of the webhook to retrieve.

Response

string

Unique identifier for the webhook.

string

ID of the organization that owns this webhook.

string

The webhook endpoint URL.

string[]

Array of event types this webhook is subscribed to.

string

ISO 8601 timestamp of when the webhook was created.

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"

const response = await fetch('https://api.sendook.com/v1/webhooks/webhook_123/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.sendook.com/v1/webhooks/webhook_123/test',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

result = response.json()

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

Path Parameters

string

required

The unique identifier of the webhook to test.

Response

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"

const response = await fetch('https://api.sendook.com/v1/webhooks/webhook_123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const deletedWebhook = await response.json();

import requests

response = requests.delete(
    'https://api.sendook.com/v1/webhooks/webhook_123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

deleted_webhook = response.json()

Delete a webhook endpoint.

Path Parameters

string

required

The unique identifier of the webhook to delete.

Response

Returns the deleted webhook object.

string

Unique identifier for the deleted webhook.

string

ID of the organization that owned this webhook.

string

The webhook endpoint URL.

string[]

Array of event types the webhook was subscribed to.

string

ISO 8601 timestamp of when the webhook was created.

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"

const response = await fetch('https://api.sendook.com/v1/webhooks/webhook_123/attempts', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const attempts = await response.json();

import requests

response = requests.get(
    'https://api.sendook.com/v1/webhooks/webhook_123/attempts',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

attempts = response.json()

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

Path Parameters

string

required

The unique identifier of the webhook.

Response

Returns an array of webhook attempt objects.

string

Unique identifier for the webhook attempt.

string

ID of the webhook this attempt belongs to.

string

The event type that triggered this webhook.

object

The data payload sent to the webhook endpoint.

string

The webhook endpoint URL that was called.

number

HTTP status code returned by the webhook endpoint.

string

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

boolean

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

number

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

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": "sender@example.com",
      "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": "sender@example.com",
    "to": ["recipient@yourdomain.com"],
    "subject": "Hello",
    "text": "Message body",
    "html": "<p>Message body</p>",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

string

The type of event that occurred.

object

The event payload. Structure varies by event type:

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

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

​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

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