Webhooks

Webhooks let CastBrick push real-time event notifications to your server. When an event occurs (e.g. an SMS is delivered or a contact opts out), CastBrick sends an HTTP POST request to your registered endpoint with a JSON payload.

Event types

Event	Trigger
`SmsSent`	An SMS has been dispatched to the carrier
`SmsDelivered`	Carrier confirmed delivery
`SmsFailed`	Delivery failed
`InboundMessage`	An inbound SMS was received
`DeliveryReceipt`	A delivery receipt was received from the carrier
`ContactCreated`	A contact was added
`ContactUpdated`	A contact was updated
`ContactDeleted`	A contact was deleted
`CampaignCreated`	A broadcast was created
`CampaignUpdated`	A broadcast was updated
`CampaignDeleted`	A broadcast was deleted
`OptOut`	A contact replied STOP or opted out
`LowBalance`	Your SMS balance fell below the alert threshold

Create a webhook

POST /webhooks

Registers a new webhook endpoint for a specific event type.

Request body

{
  "endpoint": "https://yourapp.com/webhooks/castbrick",
  "eventType": "SmsDelivered"
}

Field	Type	Required	Description
`endpoint`	`string`	Yes	HTTPS URL that will receive POST requests
`eventType`	`string`	Yes	One of the event types listed above

Response `201`

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Returns the new webhook ID.

Code sample

curl -X POST https://api.castbrick.co/webhooks \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://yourapp.com/webhooks/castbrick",
    "eventType": "SmsDelivered"
  }'

List webhooks

GET /webhooks

Returns a paginated list of your registered webhooks.

Query parameters

Parameter	Default	Description
`pageNumber`	`1`	Page number
`pageSize`	`10`	Results per page

Response `200`

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "endpoint": "https://yourapp.com/webhooks/castbrick",
      "eventType": "SmsDelivered",
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "totalCount": 3,
  "pageNumber": 1,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false
}

Code sample

curl https://api.castbrick.co/webhooks \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Get a webhook

GET /webhooks/{id}

curl https://api.castbrick.co/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Toggle active status

PUT /webhooks/{id}/toggle

Enables or disables a webhook. When disabled, no events are sent to its endpoint.

curl -X PUT https://api.castbrick.co/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/toggle \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Returns 204 No Content.

Test a webhook

POST /webhooks/test

Sends a sample payload to your webhook endpoint so you can verify it's reachable and responding correctly.

Request body

{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payload": "{\"event\":\"SmsDelivered\",\"messageId\":\"test-123\"}"
}

Code sample

curl -X POST https://api.castbrick.co/webhooks/test \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payload": "{\"event\":\"SmsDelivered\",\"messageId\":\"test-123\"}"
  }'

Delivery logs

GET /webhooks/{id}/logs

Returns the delivery history for a webhook, including status and response for each attempt.

Query parameters

Parameter	Default	Description
`limit`	`50`	Number of log entries to return

Response `200`

[
  {
    "id": "log-uuid",
    "webhookId": "3fa85f64-...",
    "eventType": "SmsDelivered",
    "statusCode": 200,
    "attempt": 1,
    "deliveredAt": "2026-05-07T10:24:00Z"
  }
]

Code sample

curl "https://api.castbrick.co/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/logs?limit=20" \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Retry a delivery

POST /webhooks/logs/{logId}/retry

Retries a failed webhook delivery by its log entry ID.

curl -X POST https://api.castbrick.co/webhooks/logs/log-uuid/retry \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Delete a webhook

DELETE /webhooks/{id}

Permanently removes a webhook. Returns 204 No Content.

curl -X DELETE https://api.castbrick.co/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Receiving events

CastBrick sends a POST request to your endpoint with a JSON body. Your server must return a 2xx status code within 10 seconds, otherwise the delivery is marked as failed and may be retried.

Example payload — `SmsDelivered`

{
  "event": "SmsDelivered",
  "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "recipientPhone": "+244923000000",
  "deliveredAt": "2026-05-07T10:23:08Z"
}

Example handler (Node.js / Express)

app.post('/webhooks/castbrick', express.json(), (req, res) => {
  const { event, messageId } = req.body;

  if (event === 'SmsDelivered') {
    console.log('Delivered:', messageId);
  } else if (event === 'SmsFailed') {
    console.warn('Failed:', messageId);
  }

  res.sendStatus(200);
});

Example handler (Python / Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/castbrick', methods=['POST'])
def handle_webhook():
    data = request.get_json()
    event = data.get('event')

    if event == 'SmsDelivered':
        print('Delivered:', data.get('messageId'))
    elif event == 'SmsFailed':
        print('Failed:', data.get('messageId'))

    return '', 200

Webhooks

On this page