Inbound webhooks

Inbound webhooks let a workspace receive events from external systems and map them into Switchbord’s transactional template-send contract.

Safety defaults

New webhook configurations are disabled and dry-run by default. A dry-run records the inbound run, verifies the signature, validates the mapping, and stores the mapped transactional request without queuing a live send. Secrets are generated once. Switchbord stores only a SHA-256 hash and a short prefix for display. List responses never include the raw secret. After creation, never send the raw secret to Switchbord; use it only to produce request signatures.

Endpoint

Each configuration gets a generated URL:

POST /api/v1/inbound-webhooks/{slug}

The endpoint resolves the workspace and webhook configuration from the URL slug. Payload fields are never trusted for tenancy resolution.

Authentication

Requests must include a timestamped HMAC signature over the exact raw request body. Do not include the raw webhook secret in headers, query parameters, or the payload.

X-Switchbord-Signature: t=<unix timestamp seconds>,v1=<hex hmac sha256>
Idempotency-Key: optional-external-event-id

The v1 HMAC signs {timestamp}.{rawBody} with the one-time secret generated when the webhook was created. Timestamps must be within five minutes of Switchbord’s clock to reduce replay risk. Multiple v1 entries are accepted so senders can retry during key rotation, but at least one must match. Example signature generation:

import { createHash, createHmac } from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(secret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const signature = `t=${timestamp},v1=${digest}`;

Signature verification uses a timing-safe comparison and happens before mapping or queueing.

Mapping

The Settings builder is the recommended way to create mappings. It loads approved Utility templates, shows the body/button/header variables each template needs, and lets you map each field from a payload path, literal, or JSON value. Runtime mappings support legacy dot-path values and explicit expressions:

{
  "to": "path:customer.phone",
  "templateName": "literal:payment_receipt_document",
  "templateLocale": "literal:it",
  "externalId": "path:receipt.id",
  "parameters.header.document.link": "path:receipt.pdf",
  "parameters.header.document.filename": "literal:receipt.pdf",
  "parameters.body.1": "path:customer.first_name",
  "parameters.body.2": "path:receipt.number"
}

Expression prefixes:

Prefix	Meaning
`path:`	Resolve a dot path from the inbound JSON payload.
`literal:`	Use the text after the prefix as the value.
`json:`	Parse the text after the prefix as JSON.
no prefix	Legacy dot-path lookup from the inbound payload.

Mapping targets may not contain __proto__, prototype, or constructor. Switchbord rejects unsafe targets before previewing or processing the webhook. Configured templateName and templateLocale values override mapped values. New configs created through Settings are restricted to the selected approved Utility template.

Run logs

Every received request for an enabled config records a run with redacted headers, payload shape metadata, sanitized mapped-request diagnostics, status, and errors. Raw customer payloads, recipient phone numbers, and template variable values are not stored in run logs by default. Invalid signatures are recorded as failed runs and return 401, but they do not reserve verified idempotency keys. Possible run statuses include verified, dry_run, queued, failed, and skipped_duplicate.

Current limitation

The runtime foundation can execute the transactional template-send service when a config is enabled, but Settings-created configs are currently forced to disabled dry-run mode and cannot be promoted through the public Settings API. A signed request to a disabled config returns 404 webhook_not_found_or_disabled. Live promotion is server-locked until a run-log verified promotion flow ships. Use Transactional template sends for production sends today.

API Reference

Safety defaults

Endpoint

Authentication

Mapping

Run logs

Current limitation

Integration guides

​Safety defaults

​Endpoint

​Authentication

​Mapping

​Run logs

​Current limitation

​Integration guides

Safety defaults

Endpoint

Authentication

Mapping

Run logs

Current limitation

Integration guides