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.

• 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.
• If 5 deliveries in a row fail, Ziflow suspends the webhook for 5 minutes. Events that occur during the suspension are not delivered to your endpoint.
• Connection errors, such as a refused connection, an unknown host, or a failed SSL handshake, do not count toward the 5 failures.
• If your endpoint's SSL certificate is invalid, Ziflow disables the webhook.

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're 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 can't change the payload's structure or content, and it doesn't 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're troubleshooting a field reference, confirm which of the two you're using first — see Build flows with Webhook Zibots for the full list of fields available in a Zibot's context.