Configuring Webhooks
Webhooks deliver calling, messaging and email events to your application, including calls answered, messages delivered and incoming emails. Manage endpoints at Developer → Webhooks.
Why webhooks
Polling the API for status doesn't scale. Webhooks let you:
- Update internal state the moment a message is delivered or bounces.
- React to compliance events (opt-outs, complaints) without manual review.
- Trigger downstream automation (CRM updates, customer success workflows).
Creating an endpoint
- Open Developer → Webhooks.
- Click Add endpoint.
- Enter the URL that will receive events. Must be HTTPS with a valid TLS certificate.
- Pick the event types you care about (at least one).
- Save. Blocx shows the signing secret — copy it to your secret manager.
Event catalog
The available event types are:
Calls
| Event | When it fires |
|---|---|
call.initiated |
An inbound or outbound call starts |
call.answered |
A call is answered |
call.ended |
A call ends, including unanswered calls |
call.bridged |
Two call legs are connected |
call.speech-ended |
Spoken text finishes playing |
call.digits-received |
A keypad digit is received |
Calling events include data.call and data.occurredAt; keypad events also include data.digit. See Call Control API for call fields and an inbound workflow.
Messages
| Event | When it fires |
|---|---|
message.sent |
Message accepted by carrier |
message.delivered |
Message delivered to recipient |
message.failed |
Message failed to deliver |
message.unconfirmed |
Delivery finalized without confirmation |
message.received |
Inbound message received |
| Event | When it fires |
|---|---|
email.delivered |
Email delivered to recipient |
email.bounced |
Email bounced |
email.complained |
Recipient marked the message as spam |
email.opened |
Recipient opened the email |
email.clicked |
Recipient clicked a link |
email.received |
Inbound email received |
For billing or compliance changes (auto-recharge results, balance alerts, brand or campaign status, port progress, domain verification), organization owners and admins receive in-app and email notifications automatically — webhook subscriptions for those events are not currently offered.
Payload shape
Events share this envelope. The contents of data depend on the event type; this example shows an answered call. The example calling rate is illustrative.
{
"id": "evt_51fcfe65-10ad-4832-a076-8d94ea09d6c4",
"type": "call.answered",
"createdAt": "2026-11-20T10:00:11.000Z",
"data": {
"occurredAt": "2026-11-20T10:00:10.000Z",
"call": {
"id": "35a4be1e-8ebe-4630-b9bd-971c3e921388",
"phoneNumberId": 123,
"direction": "outbound",
"from": "+14155550100",
"to": "+14155550123",
"status": "active",
"durationSeconds": 0,
"amountMicros": "0",
"rateMicros": "20000",
"createdAt": "2026-11-20T10:00:00.000Z",
"answeredAt": "2026-11-20T10:00:10.000Z",
"endedAt": null
}
}
}
createdAt is the notification creation time. For calls, data.occurredAt is the lifecycle event time and data.call is the call snapshot. Events can arrive late or out of order; retrieve the call when you need its latest state or charge.
Verifying signatures
Every request includes an HMAC signature header:
Blocx-Signature— formatted ast=<unix-timestamp>,v1=<hex>wherev1 = HMAC-SHA256(secret, "${t}.${rawBody}").Blocx-EventandBlocx-Event-Id— the event type and a unique event ID for idempotent processing.
To verify:
- Read the raw request body before parsing JSON — the signature is over raw bytes.
- Parse
tandv1fromBlocx-Signature. - Compute
HMAC-SHA256(secret, "${t}.${rawBody}")and compare tov1in constant time. - Reject requests whose
tis more than 5 minutes off from your server's clock to prevent replay.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody: string, signatureHeader: string, secret: string) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((p) => p.trim().split('='))
) as { t?: string; v1?: string }
if (!parts.t || !/^\d+$/.test(parts.t)) return false
if (!parts.v1 || !/^[0-9a-f]{64}$/i.test(parts.v1)) return false
const timestamp = Number(parts.t)
if (!Number.isSafeInteger(timestamp)) return false
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false
const expected = createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest()
const received = Buffer.from(parts.v1, 'hex')
return received.length === expected.length && timingSafeEqual(expected, received)
}
Idempotency
After verifying the signature, use the body's id to deduplicate; Blocx-Event-Id carries the same value. Retries or accidental redeliveries reuse that ID. Store it durably with the queued work or business update so a crash cannot cause the same event to be processed twice. For call automation, also persist each resulting commandId and reuse it when retrying the action.
Performance tips
- Respond fast. Return a 2xx within a couple of seconds. Queue heavy work; don't block on it.
- Use event data directly when possible. Retrieve current call state when recovering from delayed or out-of-order events rather than fetching for every notification.
- Scale horizontally. Bursts of
message.deliveredoremail.deliveredcan be substantial at peak.