> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Inbound webhook events overview — what they're for, where to configure them, and how they fit into Switchbord's integration surface.

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](/operations/webhooks) and [Webhook Setup](/platform/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.

<CardGroup cols={2}>
  <Card title="Generated endpoint" icon="link">
    Each webhook configuration gets its own URL under `/api/v1/inbound-webhooks/{slug}` — no shared secret across configurations.
  </Card>

  <Card title="Template mapping" icon="table-cells">
    The Settings builder loads your approved Utility templates and lets you map each variable from a payload field, a literal, or a JSON value.
  </Card>
</CardGroup>

## 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.

<Warning>
  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](/guides/webhook-dry-run-rollout) for the current status and what to do if you need production sends today.
</Warning>

## 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](/api-reference/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](/features/inbox) in the first place. That's a one-time setup step covered in [Webhook Setup](/platform/webhook-setup), and the operational model behind it (envelope storage, verification, replay) is documented in [Webhook Operations](/operations/webhooks).

## See also

* [Webhook Setup](/platform/webhook-setup) — configuring Meta to deliver WhatsApp events to your workspace.
* [Webhook Operations](/operations/webhooks) — the internal envelope model, monitoring, and replay tooling.
* [Inbound webhooks](/api-reference/inbound-webhooks) — the full authentication and mapping reference for your own integrations.
* [Inbound webhook dry-run rollout](/guides/webhook-dry-run-rollout) — current promotion status and safe testing steps.