Bulkit
Register

Webhooks Overview

Configure account-level real-time HTTP callbacks for delivery receipts and inbound messages across SMS and WhatsApp.

Last updated · Markdown version

Bulkit uses webhooks to notify your server in real time when events occur on your account. Rather than polling the API continuously, Bulkit dispatches an HTTP POST request to your public webhook endpoint whenever:

  • an outbound SMS or WhatsApp message changes status (e.g. delivered, failed, read)
  • an inbound SMS or WhatsApp message arrives from a customer

Shared Account-Level Webhooks

Webhooks in Bulkit are shared at the account level across all your API keys and campaigns. You configure two endpoints in the Bulkit dashboard under API Keys -> Webhooks:

  1. DLR Webhook URL (Delivery Reports): Receives status updates (sms.delivered, sms.failed, sms.blacklisted, whatsapp.receipt.updated).
  2. Inbox Webhook URL (Inbound Messages): Receives customer replies (sms.received, whatsapp.message.received).

Each endpoint has an Enable switch in the dashboard so you can activate or pause notifications at any time.

Webhook Headers

Bulkit sends the following standard HTTP headers with every webhook POST request:

HeaderDescriptionExample
Content-TypeMIME format of the request bodyapplication/json
X-Bulkit-Webhook-EventThe specific event identifiersms.delivered, whatsapp.message.received

Receiving Webhook Requests

When Bulkit triggers a webhook, your endpoint should:

  1. Return HTTP 200 OK promptly: Respond with an HTTP 200 status code as soon as the payload is received.
  2. Process asynchronously: Hand off heavy processing, database updates, or external API calls to background job workers (e.g. Celery, Redis queue, BullMQ, Go channels) so your HTTP response is not delayed.
  3. Handle retries idempotently: Store the unique outbox_id (SMS) or message_id (WhatsApp) so duplicate deliveries can be detected and handled safely.
cURL / Bash
// Expected response from your server:
HTTP/1.1 200 OK
Content-Type: application/json

{"status": "ok"}

Supported Events

Delivery Reports (DLR)

  • sms.delivered: SMS successfully delivered to the recipient's mobile terminal.
  • sms.failed: SMS delivery failed at the operator network.
  • sms.blacklisted: Outgoing SMS was rejected because the recipient is on the sender blacklist.
  • whatsapp.receipt.updated: WhatsApp delivery status changed (delivered or read).

Detailed documentation and JSON payloads are available in Delivery Report (DLR) Webhooks.

Inbound Messages

  • sms.received / sms.inbound: Incoming SMS sent to your shortcode or two-way number.
  • whatsapp.message.received: Inbound WhatsApp customer message (text, image, document, audio, video).

Detailed documentation and JSON payloads are available in Inbound Message Webhooks.

PreviousWhatsApp Connection StatusNextDelivery Report (DLR) Webhooks