Webhook Endpoints API

The Webhook Endpoints API provides full CRUD (Create, Read, Update, Delete) operations for managing webhook endpoint configurations. You can create, list, view, update, delete webhook endpoints, send test webhooks, and view delivery history programmatically.

Webhook endpoints allow you to receive real-time notifications about events in your Broadcast channel, such as email deliveries, subscriber changes, and broadcast status updates.

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

• Read Permission: Required for GET endpoints (list, show, deliveries)
• Write Permission: Required for POST, PATCH, DELETE endpoints (create, update, delete, test)

Webhook Endpoint Object

The webhook endpoint object contains the following fields:

Security Note

The webhook secret is used to sign webhook payloads using HMAC-SHA256. For security:

• The secret is only shown in full when creating a new webhook endpoint
• In subsequent GET requests, the secret is redacted (e.g., abcd••••••••wxyz)
• Store the secret securely when you receive it during creation
• The secret cannot be modified; create a new webhook endpoint if you need a new secret

A change made through the API is never rejected because its webhook couldn’t be sent. If a webhook had a problem, the request still succeeds and says so in a warnings array and a Broadcast-Warning header. See API Response Warnings.

Available Event Types

You can subscribe to any combination of the following event types:

Email Events

With parallel sending on (PARALLEL_BROADCAST_SENDING=true), broadcasts send broadcast.batch_completed instead of per-recipient email.sent and email.failed events. Sequential broadcasts (the default), sequences and transactional emails still send email.sent and email.failed. Delivery, open, click, bounce and complaint events are the same in both modes.

Subscriber Events

Subscriber List Events

Broadcast Events

Sequence Events

Other Events

List Webhook Endpoints

GET /api/v1/webhook_endpoints

Retrieve a list of all webhook endpoints for the authenticated broadcast channel.

Query Parameters

• limit (optional): Maximum number of endpoints to return, from 1 to 1000
• offset (optional): Number of endpoints to skip, 0 or more

A limit or offset outside those ranges, or that is not a whole number, returns 422 Unprocessable Entity.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-domain.com/api/v1/webhook_endpoints

Response

{
  "data": [
    {
      "id": 1,
      "url": "https://api.example.com/webhooks",
      "description": "Production webhook endpoint",
      "active": true,
      "event_types": ["email.sent", "email.delivered", "email.bounced"],
      "retries_to_attempt": 6,
      "secret": "abcd••••••••••••••••••••••••wxyz",
      "last_response_code": 200,
      "last_sent_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Get Webhook Endpoint

GET /api/v1/webhook_endpoints/:id

Retrieve details of a specific webhook endpoint.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-domain.com/api/v1/webhook_endpoints/1

Response

{
  "id": 1,
  "url": "https://api.example.com/webhooks",
  "description": "Production webhook endpoint",
  "active": true,
  "event_types": ["email.sent", "email.delivered", "email.bounced"],
  "retries_to_attempt": 6,
  "secret": "abcd••••••••••••••••••••••••wxyz",
  "last_response_code": 200,
  "last_sent_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Create Webhook Endpoint

POST /api/v1/webhook_endpoints

Create a new webhook endpoint.

Required Parameters

• url (required): A valid http:// or https:// URL where webhooks will be sent (HTTPS is recommended). Each URL can be used only once per channel
• event_types (required): Array of event types to subscribe to (at least one)

Optional Parameters

• description: Description of the webhook endpoint
• active: Whether the endpoint is active (default: true)
• retries_to_attempt: Maximum retry attempts (default: 6). See the retry schedule

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "url": "https://api.example.com/webhooks",
      "description": "Production webhook endpoint",
      "active": true,
      "event_types": ["email.sent", "email.delivered", "email.bounced", "subscriber.created"],
      "retries_to_attempt": 6
    }
  }' \
  https://your-domain.com/api/v1/webhook_endpoints

Response

Note: The secret is shown in full only on creation. Store it securely!

{
  "id": 1,
  "url": "https://api.example.com/webhooks",
  "description": "Production webhook endpoint",
  "active": true,
  "event_types": ["email.sent", "email.delivered", "email.bounced", "subscriber.created"],
  "retries_to_attempt": 6,
  "secret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "last_response_code": null,
  "last_sent_at": null,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Update Webhook Endpoint

PATCH /api/v1/webhook_endpoints/:id

Update an existing webhook endpoint.

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "description": "Updated description",
      "active": false,
      "event_types": ["email.sent", "email.delivered"]
    }
  }' \
  https://your-domain.com/api/v1/webhook_endpoints/1

Response

{
  "id": 1,
  "url": "https://api.example.com/webhooks",
  "description": "Updated description",
  "active": false,
  "event_types": ["email.sent", "email.delivered"],
  "retries_to_attempt": 6,
  "secret": "a1b2••••••••••••••••••••••••y5z6",
  "last_response_code": 200,
  "last_sent_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Delete Webhook Endpoint

DELETE /api/v1/webhook_endpoints/:id

Delete a webhook endpoint.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-domain.com/api/v1/webhook_endpoints/1

Response

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

Send Test Webhook

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

Send a test webhook to verify your endpoint is working correctly. The test webhook will contain realistic sample data for the specified event type.

Query Parameters

• event_type (optional): The event type to test (default: “test.webhook”). Must be one of the event types configured for this endpoint.

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "email.delivered"
  }' \
  https://your-domain.com/api/v1/webhook_endpoints/1/test

Response

{
  "message": "Test webhook queued for delivery",
  "event_type": "email.delivered",
  "delivery_id": 42
}

List Webhook Deliveries

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

Retrieve the delivery history for a webhook endpoint, including successful deliveries and failed attempts.

Query Parameters

• limit (optional): Maximum number of deliveries to return, from 1 to 1000
• offset (optional): Number of deliveries to skip, 0 or more

A limit or offset outside those ranges, or that is not a whole number, returns 422 Unprocessable Entity.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-domain.com/api/v1/webhook_endpoints/1/deliveries

Response

{
  "data": [
    {
      "id": 42,
      "event_type": "email.delivered",
      "event_data": {
        "receipt_id": 1234,
        "email": "subscriber@example.com",
        "delivered": true,
        "opened": false
      },
      "attempt_number": 1,
      "response_status": 200,
      "response_body": "OK",
      "error_message": null,
      "first_attempt_at": "2024-01-15T10:30:00Z",
      "last_attempt_at": "2024-01-15T10:30:00Z",
      "next_retry_at": null,
      "successfully_delivered_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Webhook Delivery Object

The delivery object contains information about each webhook delivery attempt:

Retry Schedule

Verifying Webhook Signatures

All webhooks are signed using HMAC-SHA256. To verify a webhook:

1. Extract the signature from the broadcast-webhook-signature header
2. Extract the timestamp from the broadcast-webhook-timestamp header
3. Create the signed payload: {timestamp}.{raw_request_body}
4. Calculate HMAC-SHA256 using your secret and the signed payload
5. Compare the calculated signature with the one in the header

Header Format

broadcast-webhook-signature: v1,{base64_encoded_signature}
broadcast-webhook-timestamp: 1705312200

Example Verification (Ruby)

def verify_webhook(payload, headers, secret)
  signature_header = headers['broadcast-webhook-signature']
  timestamp = headers['broadcast-webhook-timestamp']

  version, signature = signature_header.split(',')
  return false unless version == 'v1'

  # Check timestamp (5 minute window)
  return false if (Time.now.to_i - timestamp.to_i).abs > 300

  signed_payload = "#{timestamp}.#{payload}"
  expected = Base64.strict_encode64(
    OpenSSL::HMAC.digest('sha256', secret, signed_payload)
  )

  ActiveSupport::SecurityUtils.secure_compare(signature, expected)
end

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

Returned when the API token is missing, invalid, or lacks the required permissions.

404 Not Found

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

Returned when the specified webhook endpoint doesn’t exist or belongs to a different channel.

422 Unprocessable Entity

{
  "error": "Url is invalid, Event types must have one selected"
}

Common validation errors: - Missing or invalid URL (must be HTTP or HTTPS) - No event types selected - Duplicate URL (each URL must be unique per channel) - Invalid event type for test webhook

Example: Complete Setup Flow

# 1. Create a webhook endpoint
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "url": "https://api.myapp.com/broadcast-webhooks",
      "description": "Email event notifications",
      "event_types": ["email.sent", "email.delivered", "email.bounced", "email.opened"]
    }
  }' \
  https://your-domain.com/api/v1/webhook_endpoints

# Response: Save the secret! It won't be shown again.
# { "id": 1, "secret": "abc123...", ... }

# 2. Send a test webhook to verify your endpoint
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "email.delivered"}' \
  https://your-domain.com/api/v1/webhook_endpoints/1/test

# 3. Check the delivery history
curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-domain.com/api/v1/webhook_endpoints/1/deliveries

# 4. Verify successful delivery
# Response shows response_status: 200 and successfully_delivered_at is set