Webhooks let your Ziflow account automatically send information to other applications in real time. They provide a simple way for Ziflow to “talk” to external systems and notify them whenever specific events occur, such as when a proof is created, a comment is added, or a decision is made.

Available to administrators on: Free Standard Pro Enterprise

Log into Ziflow. Select your user avatar and choose Settings > API Settings > Webhooks.

Add a webhook endpoint

1. Select Add endpoint.

2. Fill in the webhook details:
   
   

   Webhook name	A descriptive name (e.g., Slack integration or Custom reporting).
   Webhook URL	The third-party endpoint URL where Ziflow should send data.
   Webhook signature key (optional but recommended)	Add a key to verify webhook authenticity. Ziflow uses this key to calculate a SHA-256 signature included in the x-ziflow-signature header of each event. You can use a Ziflow-generated key or provide your own (up to 255 alphanumeric characters, with “-” and “\”).
   Filter event	Choose which events to send. You can send all events or choose Send some events and select the events from a list.

3. Select Add endpoint.
4. Change the endpoint status to Active. New endpoints are disabled by default until activated.

Verify webhook signatures

To confirm that events are coming from Ziflow and not a third party, you can validate webhook signatures. The SHA-256 signature is generated using:

• webhook_signature_key
• HTTP method
• Webhook URI (URL-encoded if query parameters are included)
• Raw request body

Example raw string used in SHA-256 calculation

key: 1-app-key-34/8652
method: POST
webhook URI: https://some.endpoint.com?param=value/something
encoded webhook URI: https://some.endpoint.com?param=value%2Fsomething

Concatenated string

1-app-key-34/8652POSThttps://some.endpoint.com?param=value%2Fsomething{"events":[{...}]}

This string is then hashed with SHA-256 using the signature key.

Always use the raw request body when calculating the hash.

Edit or manage webhooks

• Select a webhook to open edit mode and update its configuration.
• Deactivate a webhook to temporarily stop event delivery.
• Delete a webhook if it’s no longer needed.

Webhook delivery and retries

If your endpoint does not accept an event, Ziflow tries to deliver it again. Ziflow tracks retries separately for each webhook endpoint.

• Your endpoint must return an HTTP 2xx response at the webhook URL. If it returns an HTTP 3xx response, Ziflow treats the event as delivered and does not follow the redirect.
• Ziflow retries a failed delivery up to 16 times and waits longer between each attempt (exponential backoff).
• Ziflow does not retry a delivery if your endpoint returns an HTTP 400, 401, 402, 403, 404, or 405 response.
• Ziflow does not keep a log of webhook deliveries. For timeouts, status codes, and the payload fields you can use to troubleshoot deliveries, see the Ziflow API documentation.

Suspended webhooks

Ziflow keeps a failure count for each webhook. A timeout or an HTTP 4xx or 5xx response adds 1 to the count, and each successful delivery subtracts 1.

• When the count reaches 5, Ziflow suspends the webhook for 5 minutes. Events and retries that Ziflow tries to send during the suspension are not delivered to your endpoint, and Ziflow does not send them later.
• After a suspension, one more failure suspends the webhook again. Each successful delivery lowers the count.
• The count resets after 1 hour without deliveries.
• Connection errors, such as a refused connection, an unknown host, or a failed SSL handshake, do not count toward the 5 failures. Ziflow still retries these deliveries.

Disabled webhooks

If your endpoint's SSL certificate is invalid, Ziflow sets the webhook to inactive and sends an email to all administrators in your account. To receive events again, fix the certificate, and then change the webhook status to Active.

Additional information

• If your webhook URL contains query parameters, ensure that values are URL-encoded before calculating the signature.
• Checklist item selected (checklist_item_selected) Enterprise: sent when a reviewer sets a checklist item to Pass, Fail, Checked, or Not Relevant, or clears it. The payload includes the checklist ID, checklist item ID, selected value, reviewer ID, and whether the value came from a ReviewAI suggestion. Endpoints set to send all events receive it automatically.
• For full event schema details and subscription management via API, see the Ziflow API documentation.

What is the difference between a webhook endpoint and a webhook Zibot?

Both send data to an external system when something happens in Ziflow, but they are different features with different payload rules — mixing them up is a common source of confusion.

A webhook endpoint (this page, Settings > API Settings > Webhooks) sends a fixed, predefined JSON structure whenever a selected event occurs, such as a proof being created or a comment being added. You choose which events to send, but you cannot change the payload's structure or content, and it does not support template expressions.

A webhook Zibot (Pro and Enterprise) is an action inside a Connect flow. You write the request body yourself using JSONata template expressions (for example, #{$.proof.name}#), which lets you pull specific fields from the flow's context into whatever format the receiving system expects.

This distinction matters most when a field doesn't resolve the way you expect. A webhook endpoint's payload never contains a proof object, so template-style paths have no effect there. If you are troubleshooting a field reference, confirm which of the two you are using first — see Build flows with Webhook Zibots for the full list of fields available in a Zibot's context.