---
title: "How to Setup SMS Webhook"
description: "Configure webhook endpoints for inbound SMS and delivery status callbacks."
---

# How to Setup SMS Webhook

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](/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

- [Inbound Messages Webhook Guide](/webhooks/inbound-messages)
- [Shortcode Inbox SMS Webhook](/sms/shortcode-inbox-sms-webhook)
- [Keyword Inbox SMS Webhook](/sms/keyword-inbox-sms-webhook)

### Delivery webhooks

- [Delivery Reports Webhook Guide](/webhooks/delivery-reports)
- [How to Get Delivery Reports](/sms/how-to-get-delivery-reports)

## Best practices

- Always expose a public HTTPS endpoint.
- Inspect the `X-Bulkit-Webhook-Event` header 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`, and `sms.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.