SMS callback URLs

A callback URL receives the events of one SMS message, or of every message on a messaging profile, in place of your webhook endpoints. Use it when a message or a program needs its own receiver.

Manage the signing secret, the attempt history and replay in the dashboard, or through the API and the bird webhooks callbacks commands. Set a profile's URL when you create a messaging profile or update one.

Choose where events go

The URL is resolved once, when the message is accepted, and kept for the message's life. A later change to the profile does not reroute a message in flight.

The URL must be HTTPS, at most 2048 characters, and a public address. A private, loopback, or link-local host returns 422.

The callback attempts list shows where a received message's event was delivered.

What the URL replaces

While a URL applies, that message's events skip your webhook endpoints. Other messages in the workspace still reach them. A failed callback does not fall back to your endpoints: use replay to recover it.

MCP Events subscriptions and connector endpoints still receive the message's events.

A messaging profile's callback_events choose which outbound events go to the URL, from sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected, and sms.expired. An event the list leaves out reaches no webhook endpoint for that message either. A profile without a list, and a send without a profile, deliver every outbound event. sms.received is never filtered. The payloads are the SMS events.

Verify signatures

Callbacks use the same Standard Webhooks headers and HMAC-SHA256 signature as webhook endpoints, so the verification code you have works unchanged. The key is your workspace's callback signing secret, one secret shared by every callback URL.

The first secret is never shown. Rotate it to get one you can use, under Webhooks → Direct callbacks in the dashboard or with Rotate callback signing secret. The new secret appears once, so store it before you leave the page. For the next 24 hours each callback is signed with both the old and the new secret, so you can deploy the new one without dropping deliveries. A workspace holds at most 5 secrets valid at once, so rotating again inside the overlap can be refused. A rotation takes effect within about a minute.

Rotate before you rely on verification: until you do, callbacks carry a signature made with a secret you cannot read.

Retries and duplicates

Callbacks follow the retry schedule of webhook endpoints: eight attempts over about 27.5 hours, and a 2xx within 15 seconds counts as success. Unlike an endpoint, a callback URL is never paused.

Delivery is at least once and not ordered. Deduplicate on the webhook-id header, and sort by the timestamp inside the payload.

Find and replay failed callbacks

The Direct callbacks tab under Webhooks in the dashboard, and List callback delivery attempts, show the workspace's callback attempts, newest first, with the URL, the status your receiver returned, and the latency. Attempts are kept for three days.

Replay failed callback deliveries queues one more attempt for each event whose callbacks failed in a time window you choose, as replaying endpoint deliveries does for endpoints. An event that was also delivered successfully within that window is skipped. A success outside the window does not count, so that event is sent again. One replay sends at most the oldest 10,000 failed events in the window; after a longer outage, replay again with a later start time for the rest.

A replay sends to the URL recorded on the failed attempts, not to your webhook endpoints and not to the profile's current URL. It recovers an outage at your receiver. It cannot recover a message sent to a wrong URL, so send that message again. Replays count toward the same daily limit as endpoint replays.

Next steps

• SMS events: the payload of each event
• Webhooks & events: signatures, retries, and replay in full
• Sending SMS: the send request