Webhooks

Add a 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

// apps/helpdesk/src/api/stripeEvents.ts
import { z } from 'zod';
import { createEndpoint } from 'zitejs/backend';

export default createEndpoint({
  description: 'Handle Stripe webhook events',
  webhook: {},                      // marks this workflow as webhook-triggered
  inputSchema: z.any(),
  outputSchema: z.object({ received: z.boolean() }),
  execute: async ({ input }) => {
    // input is the raw parsed body; verify the provider signature here
    return { received: true };
  },
});

The ingress URL

The workflow receives events at:

https://<runtime>/public/{flowId}/webhooks/{endpointId}/{token}

Segment	Value
`{flowId}`	The app’s public identifier
`{endpointId}`	The workflow’s id, as declared in `src/api/`
`{token}`	The secret that authenticates the request

The secret token in the path is the only authentication. There is no framework-level HMAC — the token is what proves the request is legitimate at the transport level. Treat the full URL as a credential, and verify provider signatures yourself (see below) when the provider supports them.

The token is provided as an environment variable named ZITE_WEBHOOK_TOKEN_<ENDPOINT>, where <ENDPOINT> is the workflow id upper-snake-cased — workflow stripeEvents becomes ZITE_WEBHOOK_TOKEN_STRIPE_EVENTS.

Verifying provider signatures

The request body is delivered raw so you can run provider-native signature verification on the exact bytes — for example, Stripe’s constructEvent:

import Stripe from 'stripe';

const stripe = new Stripe(process.env.ZITE_STRIPE_ACCESS_TOKEN);
const event = stripe.webhooks.constructEvent(rawBody, signatureHeader, process.env.ZITE_STRIPE_WEBHOOK_SECRET);

Inbound webhook bodies are limited to 1 MB.

Get started

Core concepts

Build with agents

Zite.js framework

Tutorials

Recipes

Deploy

Resources

Defining a webhook workflow

The ingress URL

Verifying provider signatures

​Defining a webhook workflow

​The ingress URL

​Verifying provider signatures

Defining a webhook workflow

The ingress URL

Verifying provider signatures