How webhooks work
- A call completes (or a run finishes)
- Bananaflow executes any
webhooknodes in the workflow asynchronously - The payload template is rendered with the run’s context and sent as a JSON
POST(or your configured method) to your endpoint - Failed deliveries are retried automatically with backoff, up to 5 attempts. Timeouts, connection errors and HTTP 408, 425, 429, 500, 502, 503 and 504 are retried; other error responses are not
Payload context variables
The following variables are available in yourpayload_template using double-brace syntax (e.g. {{workflow_run_id}}):
Call disposition
Use{{gathered_context.call_disposition}} for the raw workflow outcome or
{{gathered_context.mapped_call_disposition}} for your organization’s mapped
code. {{gathered_context.call_status}} remains the observed reason the call
ended. See Call Dispositions to configure custom business
outcomes for each workflow and understand the fallback behavior.
Bananaflow always includes a top-level
call_disposition field in the delivered
payload. If your template doesn’t set one, it is added automatically from the
raw gathered_context.call_disposition; if your template sets it explicitly,
your value is kept.Example payload template
Authentication
Webhook requests support the following authentication methods, configured via a stored credential:Receiving webhooks
Your endpoint should:- Accept
POSTrequests withContent-Type: application/json - Respond with a
2xxstatus code promptly (within 30 seconds) - Handle duplicate deliveries idempotently (retries may deliver the same payload more than once)
Minimal example receiver (Python)
Call status deliveries
What changed (2026-11-03). A call started through the API Trigger is now queued and answered
queued; it no longer gets 429 when every line is in use. Pass a status_url with the request to follow the call through its statuses.status_url, Bananaflow sends one POST to it for each status change of the call: queued, dialing, in_progress, and one final status (completed, no_answer, busy, failed or expired). The statuses are described in Call statuses. These deliveries need no webhook node.
The body holds no phone number and no context: you already have what you sent.
Retries. A delivery that fails is retried, up to 5 attempts in all, waiting 30, 60, 120 and then 240 seconds between them. Timeouts, connection errors and HTTP 408, 425, 429, 500, 502, 503 and 504 are retried; other error responses are not. Each attempt waits at most 10 seconds for your answer, so answer
2xx quickly and do the work afterwards.
Order. Deliveries can arrive out of order: a queued that failed once is sent again 30 seconds later, after dialing may have arrived. Keep the status with the highest sequence you have seen for each call, and treat final: true as the end.
Duplicates. A status is sent once per call, but a retry can deliver the same body twice. Each request carries an X-Bananaflow-Delivery-Id header that stays the same across the retries of one status, and X-Bananaflow-Delivery-Attempt with the attempt number.
Authentication. Status deliveries are not signed and carry no stored credential. Put a long, hard-to-guess token in the path of your status_url (for example https://your-service.com/bananaflow/call-status/7f3c9a...) and check it when a delivery arrives; the delivery logs keep only the address’s origin, never its path. To confirm a status, you can read the call with Get run.