How to Setup SMS Webhook
Configure webhook endpoints for inbound SMS and delivery status callbacks.
Last updated · Markdown version
Bulkit supports webhook-based integrations for inbound SMS workflows and delivery-status updates.
Use SMS webhooks when you need to:
- receive inbox messages in your application
- route shortcode traffic to your backend
- react to keyword messages automatically
- track final delivery status for outbound SMS
Configuration
Webhooks in Bulkit are configured at the account level in the dashboard under API Keys -> Webhooks tab (/api-keys).
You can configure two shared URLs across your account:
- DLR Webhook URL: Receives delivery reports (
sms.delivered,sms.failed,sms.blacklisted) and WhatsApp receipt updates. - Inbox Webhook URL: Receives inbound customer replies (
sms.received/sms.inbound) and WhatsApp messages.
For full payload schemas, examples, and headers, see the Webhooks Overview.
Headers and Authorization
Bulkit webhook dispatches include the following standard header:
X-Bulkit-Webhook-Event: The specific event type (e.g.sms.delivered,sms.failed,sms.blacklisted,sms.received).Content-Type:application/json
Webhooks should be served over HTTPS. Bulkit no longer enforces complex signing secrets, allowing you to easily process events or use standard authentication tokens in your webhook URL query strings if desired.
Webhook categories
Inbox webhooks
Delivery webhooks
Best practices
- Always expose a public HTTPS endpoint.
- Inspect the
X-Bulkit-Webhook-Eventheader to route payloads internally. - Respond quickly with
200 OK(within 5 seconds). - Process incoming payloads asynchronously using a background queue or worker.
- Handle delivery report events such as
sms.delivered,sms.failed, andsms.blacklisted.
Error response
Return a 2xx status after you accept the webhook payload. Avoid long-running processing before the response, and treat 4xx and 5xx responses as failures that may require replay or investigation.