Webhook Endpoints API

Webhook endpoints define where Broadcast delivers real-time event notifications. Each endpoint specifies a URL, the events it subscribes to, and retry behavior. Use this API to manage endpoints, send test webhooks, and inspect delivery history.

Base URL

https://app.sendbroadcast.com/api/v1

Authentication

All requests require a Bearer token with the appropriate webhook endpoint permissions. See Authentication for details.

The Webhook Endpoint Object

Field	Type	Description
`id`	integer	Unique identifier
`url`	string	HTTPS URL where webhook payloads are delivered
`description`	string	Human-readable description of the endpoint’s purpose
`active`	boolean	Whether the endpoint is enabled
`event_types`	array	List of event types this endpoint subscribes to
`retries_to_attempt`	integer	Maximum retry attempts (0-20)
`secret`	string	HMAC signing secret (shown in full only on creation, redacted otherwise)
`last_response_code`	integer	HTTP status code from the most recent delivery
`last_sent_at`	datetime	When the last webhook was sent (ISO 8601)
`created_at`	datetime	When the endpoint was created (ISO 8601)
`updated_at`	datetime	When the endpoint was last modified (ISO 8601)

Example Webhook Endpoint Object

{
  "id": 7,
  "url": "https://api.example.com/webhooks/broadcast",
  "description": "Production CRM integration",
  "active": true,
  "event_types": [
    "subscriber.created",
    "subscriber.unsubscribed",
    "email.delivered",
    "email.bounced"
  ],
  "retries_to_attempt": 6,
  "secret": "whse••••••••ab9f",
  "last_response_code": 200,
  "last_sent_at": "2025-10-01T18:45:00Z",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2025-09-20T14:30:00Z"
}

Available Event Types

Subscribe to any combination of the following events:

Email Events

Event	Description
`email.sent`	Email handed off to the delivery provider
`email.delivered`	Email confirmed delivered to the recipient
`email.delivery_delayed`	Delivery temporarily delayed
`email.bounced`	Email bounced (hard or soft)
`email.complained`	Recipient marked the email as spam
`email.opened`	Recipient opened the email
`email.clicked`	Recipient clicked a link in the email
`email.failed`	Email delivery permanently failed

Subscriber Events

Event	Description
`subscriber.created`	New subscriber added
`subscriber.updated`	Subscriber data modified
`subscriber.deleted`	Subscriber removed
`subscriber.subscribed`	Subscriber opted in
`subscriber.unsubscribed`	Subscriber opted out
`subscriber.bounced`	Subscriber marked as bounced
`subscriber.complained`	Subscriber filed a spam complaint

Broadcast Events

Event	Description
`broadcast.scheduled`	Broadcast scheduled for future delivery
`broadcast.queueing`	Broadcast is being queued for sending
`broadcast.sending`	Broadcast is actively sending
`broadcast.sent`	Broadcast finished sending to all recipients
`broadcast.failed`	Broadcast sending failed
`broadcast.partial_failure`	Broadcast sent to some but not all recipients
`broadcast.aborted`	Broadcast was manually aborted
`broadcast.paused`	Broadcast sending was paused

Sequence Events

Event	Description
`sequence.subscriber_added`	Subscriber enrolled in a sequence
`sequence.subscriber_completed`	Subscriber completed all sequence steps
`sequence.subscriber_moved`	Subscriber moved to a different step
`sequence.subscriber_removed`	Subscriber removed from a sequence
`sequence.subscriber_paused`	Subscriber’s sequence progression paused
`sequence.subscriber_resumed`	Subscriber’s sequence progression resumed
`sequence.subscriber_error`	Error occurred processing a subscriber in a sequence

System Events

Event	Description
`message.attempt.exhausted`	All delivery retry attempts have been exhausted
`test.webhook`	Test webhook sent from the dashboard or API

List Webhook Endpoints

Retrieve all webhook endpoints for the current broadcast channel.

GET /api/v1/webhook_endpoints

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of results
`offset`	integer	No	Number of records to skip

Request

curl -X GET "https://app.sendbroadcast.com/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "data": [
    {
      "id": 7,
      "url": "https://api.example.com/webhooks/broadcast",
      "description": "Production CRM integration",
      "active": true,
      "event_types": ["subscriber.created", "subscriber.unsubscribed", "email.delivered", "email.bounced"],
      "retries_to_attempt": 6,
      "secret": "whse••••••••ab9f",
      "last_response_code": 200,
      "last_sent_at": "2025-10-01T18:45:00Z",
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2025-09-20T14:30:00Z"
    }
  ],
  "total": 1
}

Get a Webhook Endpoint

Retrieve a single webhook endpoint by its ID.

GET /api/v1/webhook_endpoints/:id

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The webhook endpoint ID

Request

curl -X GET "https://app.sendbroadcast.com/api/v1/webhook_endpoints/7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

Returns the full webhook endpoint object.

Create a Webhook Endpoint

Register a new URL to receive webhook events. The signing secret is generated automatically and returned in full only in the creation response. Store it securely.

POST /api/v1/webhook_endpoints

Request Body

Field	Type	Required	Description
`webhook_endpoint[url]`	string	Yes	HTTPS URL to receive payloads
`webhook_endpoint[description]`	string	No	Description of the endpoint’s purpose
`webhook_endpoint[event_types]`	array	Yes	Event types to subscribe to
`webhook_endpoint[retries_to_attempt]`	integer	No	Max retries, 0-20 (default varies)
`webhook_endpoint[active]`	boolean	No	Enable or disable (default: true)

Request

curl -X POST "https://app.sendbroadcast.com/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "url": "https://api.example.com/webhooks/broadcast",
      "description": "CRM subscriber sync",
      "event_types": [
        "subscriber.created",
        "subscriber.updated",
        "subscriber.unsubscribed"
      ],
      "retries_to_attempt": 6
    }
  }'

Response `201 Created`

The response includes the full secret value. This is the only time the unredacted secret is returned.

{
  "id": 8,
  "url": "https://api.example.com/webhooks/broadcast",
  "description": "CRM subscriber sync",
  "active": true,
  "event_types": ["subscriber.created", "subscriber.updated", "subscriber.unsubscribed"],
  "retries_to_attempt": 6,
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "last_response_code": null,
  "last_sent_at": null,
  "created_at": "2025-10-05T11:00:00Z",
  "updated_at": "2025-10-05T11:00:00Z"
}

Update a Webhook Endpoint

Modify an existing webhook endpoint’s URL, events, or settings.

PATCH /api/v1/webhook_endpoints/:id

Request

curl -X PATCH "https://app.sendbroadcast.com/api/v1/webhook_endpoints/8" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "event_types": [
        "subscriber.created",
        "subscriber.updated",
        "subscriber.unsubscribed",
        "email.bounced",
        "email.complained"
      ],
      "retries_to_attempt": 10
    }
  }'

Response

Returns the updated webhook endpoint object with the secret redacted.

Delete a Webhook Endpoint

Permanently remove a webhook endpoint. Pending deliveries will be cancelled.

DELETE /api/v1/webhook_endpoints/:id

Request

curl -X DELETE "https://app.sendbroadcast.com/api/v1/webhook_endpoints/8" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "message": "Webhook endpoint deleted successfully"
}

Send a Test Webhook

Trigger a test webhook delivery to verify your endpoint is working correctly.

POST /api/v1/webhook_endpoints/:id/test

Request Body

Field	Type	Required	Description
`event_type`	string	No	Event type to simulate (default: `test.webhook`). Must be one the endpoint subscribes to.

Request

curl -X POST "https://app.sendbroadcast.com/api/v1/webhook_endpoints/7/test" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "subscriber.created" }'

Response

{
  "message": "Test webhook queued for delivery",
  "event_type": "subscriber.created",
  "delivery_id": 1234
}

List Deliveries

View the delivery history for a specific webhook endpoint, including response codes, errors, and retry status.

GET /api/v1/webhook_endpoints/:id/deliveries

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of results
`offset`	integer	No	Number of records to skip

Request

curl -X GET "https://app.sendbroadcast.com/api/v1/webhook_endpoints/7/deliveries?limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "data": [
    {
      "id": 501,
      "event_type": "subscriber.created",
      "event_data": {
        "subscriber_id": 4521,
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "subscribed_at": "2025-10-01T14:30:00Z",
        "is_active": true,
        "source": "opt-in"
      },
      "attempt_number": 1,
      "response_status": 200,
      "response_body": "{\"status\":\"ok\"}",
      "error_message": null,
      "first_attempt_at": "2025-10-01T14:30:05Z",
      "last_attempt_at": "2025-10-01T14:30:05Z",
      "next_retry_at": null,
      "successfully_delivered_at": "2025-10-01T14:30:05Z",
      "created_at": "2025-10-01T14:30:05Z",
      "updated_at": "2025-10-01T14:30:05Z"
    }
  ],
  "total": 142
}

Error Responses

404 Not Found

{
  "error": "Webhook endpoint not found"
}

422 Unprocessable Content

{
  "error": "Url can't be blank, Event types can't be blank"
}

Required Permissions

Action	Permission
List / Get / Deliveries	`webhook_endpoints_read`
Create / Update / Delete / Test	`webhook_endpoints_write`

Next: Webhooks Guide – Learn how to receive, verify, and process webhook events from Broadcast.

Webhook Endpoints API

Base URL

Authentication

The Webhook Endpoint Object

Example Webhook Endpoint Object

Available Event Types

Email Events

Subscriber Events

Broadcast Events

Sequence Events

System Events

List Webhook Endpoints

Query Parameters

Request

Response

Get a Webhook Endpoint

Path Parameters

Request

Response

Create a Webhook Endpoint

Request Body

Request

Response 201 Created

Update a Webhook Endpoint

Request

Response

Delete a Webhook Endpoint

Request

Response

Send a Test Webhook

Request Body

Request

Response

List Deliveries

Query Parameters

Request

Response

Error Responses

404 Not Found

422 Unprocessable Content

Required Permissions

Response `201 Created`