Webhooks

Configure webhooks to receive real-time notifications for inbox and message events.

Webhooks let you receive real-time notifications when events occur in your Sendook organization. Configure webhook endpoints to be notified of inbox changes, message deliveries, bounces, and more.

Available events

Webhooks support the following event types:

Event	Description
`inbox.created`	Triggered when a new inbox is created.
`inbox.deleted`	Triggered when an inbox is deleted.
`inbox.updated`	Triggered when an inbox is updated.
`message.sent`	Triggered when a message is sent from an inbox.
`message.received`	Triggered when a message is received by an inbox.
`message.delivered`	Triggered when a message is successfully delivered.
`message.bounced`	Triggered when a message bounces.
`message.complained`	Triggered when a recipient marks a message as spam.
`message.rejected`	Triggered when a message is rejected before delivery.

Create a webhook

Method: POST
Path: /v1/webhooks
Auth: Required

Request body

{
  "url": "https://example.com/webhooks/sendook",
  "events": ["message.received", "message.delivered"]
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL where webhook events will be sent.
`events`	string	Yes	Array of event types to subscribe to (must contain at least one event).

Response `201 Created`

{
  "id": "wh_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
  "url": "https://example.com/webhooks/sendook",
  "events": ["message.received", "message.delivered"],
  "createdAt": "2024-10-10T19:30:15Z",
  "updatedAt": "2024-10-10T19:30:15Z"
}

List webhooks

Method: GET
Path: /v1/webhooks
Auth: Required

Response `200 OK`

[
  {
    "id": "wh_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
    "url": "https://example.com/webhooks/sendook",
    "events": ["message.received", "message.delivered"],
    "createdAt": "2024-10-10T19:30:15Z",
    "updatedAt": "2024-10-10T19:30:15Z"
  }
]

Retrieve webhook details

Method: GET
Path: /v1/webhooks/{webhookId}
Auth: Required

Path parameters

Parameter	Type	Description
`webhookId`	string	The unique identifier of the webhook.

Response `200 OK`

{
  "_id": "wh_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
  "url": "https://example.com/webhooks/sendook",
  "events": ["message.received", "message.delivered"],
  "createdAt": "2024-10-10T19:30:15Z",
  "updatedAt": "2024-10-10T19:30:15Z"
}

Test a webhook

Method: POST
Path: /v1/webhooks/{webhookId}/test
Auth: Required

Sends a test webhook event to verify your endpoint is configured correctly. The test event uses message.received with a test payload.

Path parameters

Parameter	Type	Description
`webhookId`	string	The unique identifier of the webhook to test.

Response `200 OK`

{
  "success": true
}

Delete a webhook

Method: DELETE
Path: /v1/webhooks/{webhookId}
Auth: Required

Deleting a webhook stops all event notifications to that endpoint.

Response `200 OK`

{
  "id": "wh_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
  "url": "https://example.com/webhooks/sendook",
  "events": ["message.received", "message.delivered"],
  "createdAt": "2024-10-10T19:30:15Z",
  "updatedAt": "2024-10-10T19:30:15Z"
}

List webhook attempts

Method: GET
Path: /v1/webhooks/{webhookId}/attempts
Auth: Required

Retrieves the delivery history for a specific webhook, including successful deliveries and failures.

Path parameters

Parameter	Type	Description
`webhookId`	string	The unique identifier of the webhook.

Response `200 OK`

[
  {
    "id": "wa_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
    "webhookId": "wh_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
    "organizationId": "org_01J3ZP8K9M2N3O4P5Q6R7S8T9U",
    "inboxId": "ibox_01J3ZKZ0BRQ9SSJK1GRSCX4N4Z",
    "messageId": "msg_01J3ZN9SB2M5MHF5C2QBP4DT78",
    "timestamp": "2024-10-10T19:30:15Z",
    "payload": {
      "event": "message.received",
      "inboxId": "ibox_01J3ZKZ0BRQ9SSJK1GRSCX4N4Z",
      "messageId": "msg_01J3ZN9SB2M5MHF5C2QBP4DT78",
      "payload": {}
    },
    "status": 200,
    "error": null,
    "response": {
      "received": true
    },
    "createdAt": "2024-10-10T19:30:15Z",
    "updatedAt": "2024-10-10T19:30:15Z"
  }
]

Field	Type	Description
`id`	string	Unique identifier for the webhook attempt.
`webhookId`	string	The webhook that was triggered.
`organizationId`	string	The organization that owns the webhook.
`inboxId`	string	The inbox associated with the event (if applicable).
`messageId`	string	The message associated with the event (if applicable).
`timestamp`	string (date-time)	When the webhook was sent.
`payload`	object	The payload that was sent to the webhook endpoint.
`status`	integer	HTTP status code returned by the webhook endpoint.
`error`	string	Error message if the delivery failed.
`response`	object	Response body returned by the webhook endpoint.

Webhook payload format

When an event occurs, Sendook sends a POST request to your webhook URL with the following payload structure:

{
  "event": "message.received",
  "inboxId": "ibox_01J3ZKZ0BRQ9SSJK1GRSCX4N4Z",
  "messageId": "msg_01J3ZN9SB2M5MHF5C2QBP4DT78",
  "payload": {
    // Event-specific payload data
  }
}

Field	Type	Description
`event`	string	The event type that triggered the webhook.
`inboxId`	string	The inbox ID associated with the event (if applicable).
`messageId`	string	The message ID associated with the event (if applicable).
`payload`	object	Event-specific data containing the full resource details.

Example webhook payload

For a message.received event:

{
  "event": "message.received",
  "inboxId": "ibox_01J3ZKZ0BRQ9SSJK1GRSCX4N4Z",
  "messageId": "msg_01J3ZN9SB2M5MHF5C2QBP4DT78",
  "payload": {
    "id": "msg_01J3ZN9SB2M5MHF5C2QBP4DT78",
    "subject": "Welcome to Sendook",
    "text": "Plain text version of the email.",
    "html": "<p>HTML version of the email.</p>",
    "labels": ["inbound"],
    "createdAt": "2024-10-10T19:22:10Z"
  }
}

Webhook delivery

Webhooks are sent via POST requests to your configured URL.
Your endpoint should respond with a 2xx status code to acknowledge receipt.
Failed deliveries may be retried automatically.
Ensure your endpoint is accessible via HTTPS and responds within 15 seconds.

Tip: Use the test endpoint to verify your webhook configuration before relying on it for production events.

Threads

Inspect conversation threads scoped to a specific inbox.