webhook trigger to a workflow and it runs whenever an external service
(Stripe, GitHub, a form provider) POSTs to its ingress URL.
These are inbound webhooks handled by your app’s code. For outbound webhooks that notify your
systems when database records change, see the Database API webhooks.
Defining a webhook workflow
webhook: { paused: true } to stop accepting deliveries without removing the trigger. Deliveries run
only against the published app.
The ingress URL
The workflow receives events at:
The token is provided as an environment variable named
ZITE_WEBHOOK_TOKEN_<ENDPOINT>, where <ENDPOINT>
is the workflow id upper-snake-cased, so workflow stripeEvents becomes
ZITE_WEBHOOK_TOKEN_STRIPE_EVENTS.
What the workflow receives
input is the request body, parsed from JSON or from a form-encoded body. A body that is not an object
(an array or a scalar) is rejected with a 400 before the workflow runs. The body is not checked against
inputSchema, and its defaults are not applied, so read optional fields defensively.
The request headers are on input.__webhook.headers, lowercased, with authorization and cookie
removed. context.user is null on a webhook run.
The raw request bytes are not passed to the workflow, so signature checks that need the exact body (such
as Stripe’s constructEvent) can’t run there. The URL token is what authenticates the request.
Providers retry failed deliveries, so the same event can arrive more than once. Deduplicate on a stable
id from the body (input.id for Stripe) or a header (x-github-delivery for GitHub). Respond within
about 30 seconds, since most providers retry on a timeout.
Inbound webhook bodies are limited to 1 MB.