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:

Creating an endpoint

  1. Open Developer → Webhooks.
  2. Click Add endpoint.
  3. Enter the URL that will receive events. Must be HTTPS with a valid TLS certificate.
  4. Pick the event types you care about (at least one).
  5. 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

Email

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:

To verify:

  1. Read the raw request body before parsing JSON — the signature is over raw bytes.
  2. Parse t and v1 from Blocx-Signature.
  3. Compute HMAC-SHA256(secret, "${t}.${rawBody}") and compare to v1 in constant time.
  4. Reject requests whose t is 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

Related articles