Skip to main content

​
What is the workflow webhook?

A workflow can send your server one POST per execution, the moment that execution finishes — completed, failed, cancelled or aborted. The single payload carries how the execution ended plus the full trail of every node the contact passed through, so you never need to poll the execution APIs to learn an outcome. The webhook belongs to the workflow, in its settings. Setting a URL turns it on; it applies to every execution of the workflow, including ones already running.

​
Endpoints

​
Configure the webhook

Set the URL and the headers to send with every delivery through the Update Workflow API:
settings is merged into what is stored, so send only what changes: {"settings": {"webhook": {"headers": {"X-Old": null}}}} removes one header and keeps the rest, and {"settings": {"webhook": null}} stops sending webhooks. Reading the workflow back returns every header value as **********. The URL must be https on port 443 or 8443, and its host can’t be a private, loopback, link-local or carrier-NAT IP address. Redirects are not followed. Moving the URL to a different host or port drops the stored headers, so send them again in the same request.

​
The payload

Every field is described on the Execution webhook payload page. status says how the execution ended and outcome which end node it reached — reaching any end node is completed, so read outcome to tell a success from a handled failure.

​
Delivery

  • One delivery per execution, sent when it finishes. Contacts still waiting to start when a campaign is aborted never begin an execution, so they send nothing.
  • Reply with a 2xx as soon as you have accepted the payload. A non-2xx reply, a redirect, or no reply within 10 seconds is logged as a failed delivery and not attempted again on its own.
  • Resend to recover. The Resend Webhook API sends the original payload again, to the workflow’s current URL and headers. Key your handler on execution_id, since a resend repeats it.
  • No ordering between executions. Each payload is self-contained.
For the full walkthrough — testing before you run, reading the trail, and the status combinations worth handling — see the Execution webhook guide.