Skip to main content
Bananaflow executes webhook nodes asynchronously after a workflow run completes. You configure the target URL, HTTP method, headers, and payload template directly in the workflow definition.

How webhooks work

  1. A call completes (or a run finishes)
  2. Bananaflow executes any webhook nodes in the workflow asynchronously
  3. The payload template is rendered with the run’s context and sent as a JSON POST (or your configured method) to your endpoint
  4. 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 your payload_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 POST requests with Content-Type: application/json
  • Respond with a 2xx status 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.
When a call request names a 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.

Webhook node in a workflow definition

See Workflow Definition Schema for the full configuration reference.