Skip to main content
Switchbord uses webhooks in two directions. Meta sends webhooks to Switchbord for every WhatsApp message, delivery status, and template update — that’s how your inbox stays live. Separately, Switchbord can receive webhooks from your own external systems (a booking platform, a payment processor, a CRM) and turn them into outbound WhatsApp sends. This page covers the second kind — the integration surface operators configure. This is the lighter, operator-facing introduction. For the full technical contract — envelope schema, HMAC signature format, replay tooling — see Webhook Operations and Webhook Setup.

​
What inbound webhooks are for

If an external system needs to trigger a WhatsApp message when something happens elsewhere — a receipt is generated, an order ships, an appointment is booked — you don’t have to write custom integration code. You configure a webhook endpoint in Switchbord, map the external event’s fields to an approved template’s variables, and the external system POSTs to that endpoint whenever the event occurs.

Generated endpoint

Each webhook configuration gets its own URL under /api/v1/inbound-webhooks/{slug} — no shared secret across configurations.

Template mapping

The Settings builder loads your approved Utility templates and lets you map each variable from a payload field, a literal, or a JSON value.

​
Configuring one

Inbound webhooks are configured from Settings → Integrations → Webhooks & API:
  1. Click Create webhook.
  2. Select an approved Utility template.
  3. Map the template’s variables to fields in your external system’s payload.
  4. Paste a sample payload and run the dry-run preview to confirm the mapping resolves correctly — this happens entirely in the browser and never sends a message.
  5. Create the webhook once the preview passes. The signing secret is shown once — copy it into your external system’s secret store immediately, since Switchbord only ever stores a hash after that.
New webhook configurations are created disabled and in dry-run mode by default, as a safety measure. A dry-run verifies the signature and validates the mapping without queuing a live send. Live promotion for Settings-created webhooks is currently server-locked pending verified promotion controls — see the dry-run rollout guide for the current status and what to do if you need production sends today.

​
Authenticating requests

Every request must carry a timestamped HMAC signature over the raw request body, generated with the one-time secret shown at creation. Switchbord verifies this with a timing-safe comparison before touching the mapping or queueing anything. The full signature format and a working code sample live in Inbound webhooks.

​
Meta’s webhooks (the other direction)

Separately, your WhatsApp number needs Meta configured to send its webhooks to Switchbord — this is what makes messages show up in your Inbox in the first place. That’s a one-time setup step covered in Webhook Setup, and the operational model behind it (envelope storage, verification, replay) is documented in Webhook Operations.

​
See also