Webhooks

Inbound webhooks let external systems — Five9, Stripe, anything that can POST — trigger a definition. An admin creates a webhook config bound to an active definition; the external sender POSTs signed deliveries to a per-customer receive URL; each verified delivery starts a normal batch (trigger_type: "webhook", with webhook_id + delivery_id in the batch metadata).

This surface is inbound-only. Outbound webhooks — workflow tasks calling external URLs — are a separate future REST catalog action, not receiver machinery.

Not to be confused with the inbound-email receiver. Delivering an email reply back into a parked send-and-wait step uses a different endpoint that has nothing to do with the machinery on this page.

	Webhook trigger (this page)	Inbound-email receiver
Who calls it	Any system you configure	Postmark only
How it is trusted	An HMAC signature using your signing secret	HTTP basic auth plus an unguessable secret segment in the URL path, both compared in constant time
What it does	Starts a new batch	Resumes a run that is already parked
Do you configure it?	Yes — you create it and give the URL to your sender	No. Nothing to create, no secret to hold, no URL to hand out

Everything on this page — creating a config, holding a signing secret, rotating it, reading deliveries — applies to the webhook trigger and to nothing else. The reply path is set up as part of enabling inbound mail on a sending domain; see human in the loop.

{
  "id": "8a9c86a8b78c48d3a3e5e00ad0ed5b96",
  "definition_id": "def_a1b2c3d4",
  "description": "Five9 call-completed events",
  "mode": "trigger",
  "provider": "standard",
  "enabled": true,
  "receive_url": "/flows/webhooks/acme/8a9c86a8b78c48d3a3e5e00ad0ed5b96"
}

The webhook object

Field	Type	Description
`id`	string	128-bit opaque hex identifier — the receive URL is unguessable by construction.
`definition_id`	string	Definition to trigger. Must belong to your org and be re-validated as `active` at dispatch time.
`org_id`	string	Owning organization.
`description`	string	Human-readable description (1–200 chars).
`mode`	string	`trigger` (each delivery starts a new batch). `resume` is reserved and rejected with `422`. Immutable after create.
`provider`	string	Signature-verification adapter. Only `standard` (Standard Webhooks HMAC-SHA256) is implemented; `stripe`/`five9`/`custom` are rejected with `422`. Immutable after create.
`input_template`	object \| null	Optional `{{ }}`-expression mapping from the normalized `payload` context to the definition’s `input_data`. Omit to pass the whole normalized payload through.
`dispatch_retry`	object \| null	Admin-authored dispatch retry policy, default OFF (one attempt), e.g. `{"max_attempts": 3, "backoff": 5}`. Never read from the sender’s body.
`rate_limit`	integer \| null	Per-webhook deliveries/minute cap. Default `1000`.
`enabled`	boolean	`false` makes the receive URL answer `404`.
`signing_secret`	string	Show-once. Returned only on create and rotate — never retrievable from any `GET`. Store it in the sending system immediately.
`receive_url`	string	Show-once relative path — it already carries its `/flows` group. Prepend only `https://api.getdialed.ai/v1` before handing it to a sender.

The receive URL

The receiver path is POST /flows/webhooks/{slug}/{webhook_id}. In production the API is served under the /v1 base, and webhooks live in the flows product group, so the URL external senders must call is:

https://api.getdialed.ai/v1/flows/webhooks/{slug}/{webhook_id}

The receive_url returned at create time is a relative path: it omits the host and the /v1 version segment, but it does include its /flows group. So prepend https://api.getdialed.ai/v1 — host and version only — when configuring your sender, and do not add /flows a second time. The {slug} identifies your tenant; the 128-bit {webhook_id} is unguessable.

Signature verification

The receiver carries no X-API-Key / Authorization requirement — the trust boundary is the HMAC-SHA256 signature over the raw request body, verified per the Standard Webhooks spec before the body is parsed. Every sender must sign each delivery with the webhook’s signing secret, or the delivery is rejected with 401.

Senders include three Standard Webhooks headers on every delivery:

Header	Description
`webhook-id`	Sender-chosen unique delivery ID. This is the idempotency key — re-sending the same value is safe.
`webhook-timestamp`	Unix seconds. Deliveries outside the 5-minute replay window are rejected with `401`.
`webhook-signature`	`v1,<base64 HMAC-SHA256>` computed over `{webhook-id}.{webhook-timestamp}.{raw body}` with the signing secret.

The 401 message is deliberately generic — a missing header, an expired timestamp, a tampered body, and a wrong secret all return the same {"detail": "Signature verification failed"}, revealing nothing to a probing caller. Existence failures (unknown slug, unknown webhook_id, or a disabled webhook) always return 404, never 401.

Delivery semantics

202-async. The receiver acknowledges within ~50ms with 202 Accepted; batch creation and dispatch happen asynchronously after the ack. Check the deliveries view for the outcome.
Deduplication. Exactly one batch per webhook-id. A replayed delivery returns 202 but does not dispatch again — sender retry storms collapse to one batch.
Rate limit. Each webhook accepts up to rate_limit deliveries/minute (default 1000/min), counted per webhook_id (not per source IP, so senders sharing egress IPs don’t throttle each other). Over-limit deliveries get 429.
Body format. Content-Type drives normalization — JSON is parsed, form-urlencoded becomes a dict, XML is parsed with a hardened parser, anything else is wrapped as {"raw": ..., "content_type": ...}. The receiver never rejects on format.

Managing webhooks

All management endpoints require authentication and operate only on your organization’s webhooks. Mutating endpoints require an admin-role caller (an X-API-Key is admin-equivalent).

Method	Endpoint	Purpose
`POST`	`/flows/webhooks`	Create a config and mint its signing secret. Returns `201` with the show-once `signing_secret` + `receive_url`.
`GET`	`/flows/webhooks`	List your org’s webhooks with cursor pagination. The secret never appears on the read model.
`GET`	`/flows/webhooks/{webhook_id}`	Fetch one config (no secret, no receive URL).
`PATCH`	`/flows/webhooks/{webhook_id}`	Partial update — rebind `definition_id`, edit `description`/`input_template`/`dispatch_retry`/`rate_limit`/`enabled`. `mode`/`provider` are immutable.
`POST`	`/flows/webhooks/{webhook_id}/rotate-secret`	Rotate the signing secret with a 24-hour previous-secret overlap. Returns the new secret once.
`DELETE`	`/flows/webhooks/{webhook_id}`	Delete the config and scrub its stored signing secret. Returns `204`.
`GET`	`/flows/webhooks/{webhook_id}/deliveries`	Recent deliveries — the debugging view for “did my sender’s POST arrive and start a batch?”.
`POST`	`/flows/webhooks/{slug}/{webhook_id}`	The receiver — called by your external system, HMAC-signed, no API key. Returns `202`.

Creating one:

curl -X POST "$BASE_URL/flows/webhooks" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_id": "def_a1b2c3d4",
    "description": "Five9 call-completed events"
  }'

The signing_secret is returned exactly once — on create and on rotate-secret. Rotation keeps the previous secret valid for 24 hours so you can migrate senders without a hard cutover. If you lose a secret, rotate to mint a new one rather than recreating the webhook (which would change the receive URL).

Next steps

Receive webhooks

A step-by-step walkthrough: create a webhook, sign a delivery, and confirm the batch.

Event subscriptions

Trigger definitions from internal business events instead of external POSTs.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

The webhook object

The receive URL

Signature verification

Delivery semantics

Managing webhooks

Next steps

Receive webhooks

Event subscriptions

​The webhook object

​The receive URL

​Signature verification

​Delivery semantics

​Managing webhooks

​Next steps

Receive webhooks

Event subscriptions

The webhook object

The receive URL

Signature verification

Delivery semantics

Managing webhooks

Next steps