> ## Documentation Index
> Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow callback node

> Pause a workflow execution until your own system POSTs to the node's callback URL, or a timeout elapses, then branch on what it sent.

## When to use it

Some steps in a journey depend on something only your system knows: a payment landing, a KYC check passing, a form being submitted, a deal changing stage in your CRM. A `time` node can only guess how long that takes, and polling with an `api` node inside a retry loop burns attempts. The callback node pauses the contact's execution until your system sends a `POST` to the node's callback URL, or until the timeout elapses, and then the journey continues through the node's cases. Use it whenever the next step should follow an event in your system rather than the clock. To build one end to end with curl, follow [Pause a journey until your system responds](https://www.bolna.ai/docs/workflows/callback-guide.md).

***

## Configuration

Add **Callback** from the **External** group of the node catalog. Its Inspector has two steps.

The **Endpoint** step sets up the URL your system calls:

* **Callback URL** — `https://hooks.bolna.ai/callbacks/{slug}`, one per node. Copy it into the system that will send the event.
* **Signing secret** — the key your system [signs requests](#signing-requests) with.
* **Rotate** — issues a new URL and signing secret. The old URL stops resuming executions within a minute. It answers `202` for 7 days so your retries don't error, then `404`. Executions already waiting are reached through the new URL.
* **Require signature** — rejects any request without a valid signature.
* **Timeout** — how long to wait before the node takes its Timed out case, `timeout_s` below.

The **Map & Test** step decides what the node reads from a request:

* **Wait for a test event** or **Paste a sample** — loads a real request body. Wait for a test event shows the next request sent to the URL.
* **Pick the identifier** in the payload tree — the field that identifies the contact, saved as `correlation.payload_path`.
* **Matches** — the contact field the identifier must equal, saved as `correlation.matches`.
* **Tick the values to keep** — each ticked field becomes a `payload_map` entry and a `callback.<name>` variable.
* **Next-case preview** — shows which case the node would take for the sample body.

Building through the API instead? The URL exists as soon as the node is saved in a draft. Fetch it with its signing secret from the [Get Callback URL API](https://www.bolna.ai/docs/api-reference/workflows/get-callback.md), `GET /workflows/{workflow_id}/nodes/{node_id}/callback`.

Once the workflow has been published, the URL stays the same when you rename the node or publish again. Before the first publish, renaming the node in the editor changes its id, and with it the URL. Publishing a version without the node revokes its URL. A URL stays live while a campaign that hasn't completed or been aborted still runs a published version that contains the node. Once the URL is revoked, executions already waiting at that node keep waiting until their `timeout_s`, then continue with `callback.status` `"timeout"`.

| Config | Type | Default | Notes |
| - | - | - | - |
| `correlation.payload_path` | string | required | Dotted path into the request body that identifies the contact, e.g. `lead.phone`. Numeric segments index arrays, e.g. `leads.0.phone` |
| `correlation.matches` | string | `entry.mobile_number` | The contact field that value must equal: a field declared on the start node, or a system field such as `entry.reference_id` |
| `payload_map` | object | `{}` | Maps names to dotted paths into the request body, e.g. `{"amount": "payment.amount"}`. `status` is reserved |
| `require_signature` | boolean | `false` | Reject requests without a valid `X-Bolna-Signature` header |
| `timeout_s` | integer | `86400` | 60–2592000 (60 seconds to 30 days). When it elapses, `callback.status` is `"timeout"` |

> [!WARNING]
>
> A waiting execution is still in flight, so it counts toward your organisation's in-flight execution budget until it resumes or times out. That budget is shared across every campaign, so a long `timeout_s` on a large campaign holds capacity that new contacts in any campaign would otherwise use.

### Matching a request to a contact

Every request has to say which contact it is about. The node reads the value at `correlation.payload_path` in the body and resumes the execution waiting at this node whose `correlation.matches` field equals it.

* **Phone numbers are normalised to their full international form.** This covers `entry.mobile_number` and any field declared `phone`. Spaces, dashes and parentheses are ignored, and a number without a country code is read as an Indian (+91) number. `9876543210`, `09876543210`, `0091 98765-43210` and `+91 98765-43210` all match `+919876543210`. Sending the full international form is still the safest.
* **Other declared fields are coerced to their type first.** For a `number` field, `00123` matches `123` and `1001.0` matches `1001`. A field declared `email` ignores case, so `Asha@Example.com` matches `asha@example.com`. Text fields, and system fields you haven't declared, compare as trimmed, case-sensitive text.
* **A contact with no value in that field never waits.** The node skips the wait and takes its `timeout` branch at once, with a `missing_correlation_value` warning on the execution.
* **The most recent execution wins.** If several executions are waiting for the same contact at the same node, the one that entered most recently resumes.
* **Early events are not buffered.** A request that arrives before the execution reaches the node finds nothing waiting and is discarded. Place the callback node directly after the step that prompts the event.

***

## Request contract

Send a `POST` with a JSON body of up to 256 KB to the node's callback URL. The request carries no Bolna API key, so treat the URL as a secret, and turn on **Require signature** when you need proof that a request came from your system.

```bash request theme={"system"}
curl -X POST https://hooks.bolna.ai/callbacks/{slug} \
  -H "Content-Type: application/json" \
  -d '{
        "event": "payment.captured",
        "lead": {"phone": "+919876543210"},
        "payment": {"id": "pay_29QQoUBi66xm2f", "amount": 4999, "currency": "INR"}
      }'
```

| Status | Meaning |
| - | - |
| `202` | Accepted. The body is `{"status": "accepted", "match": "matched"}` when a waiting execution took the request. `match` is `"none"` when no execution is waiting for that contact, when it was already resumed, or when the URL was revoked within the last 7 days, so a caller never learns which URLs are live |
| `400` | The body is not valid JSON |
| `401` | `X-Bolna-Signature` is wrong, or missing while **Require signature** is on |
| `404` | Unknown URL, or one revoked more than 7 days ago |
| `413` | The body is larger than 256 KB |
| `415` | `Content-Type` is not `application/json` or another `application/*+json` type |
| `429` | Over the URL's budget of 1000 requests per minute by default. `Retry-After` says when to try again |
| `503` | Bolna could not durably accept the request yet. `Retry-After` says when to try again |

Treat any `2xx` as delivered. A `4xx` other than `429` will never succeed, so don't retry it. Retry a `429` after `Retry-After`, and any `5xx` with backoff.

### Signing requests

Add an `X-Bolna-Signature` header carrying `sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with the node's signing secret. Sign the exact bytes you send, because re-serialising the JSON changes them.

The signing secret is a 64-character hex string. Use it as the literal ASCII key, and don't hex-decode it first.

```bash bash theme={"system"}
BODY='{"lead":{"phone":"+919876543210"},"payment":{"id":"pay_29QQoUBi66xm2f","amount":4999}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | sed 's/^.* //')

curl -X POST https://hooks.bolna.ai/callbacks/{slug} \
  -H "Content-Type: application/json" \
  -H "X-Bolna-Signature: sha256=$SIG" \
  --data-raw "$BODY"
```

```python python theme={"system"}
import hashlib, hmac, json, requests

body = json.dumps({"lead": {"phone": "+919876543210"}, "payment": {"id": "pay_29QQoUBi66xm2f", "amount": 4999}}).encode()
sig = hmac.new(SIGNING_SECRET.encode(), body, hashlib.sha256).hexdigest()

requests.post(
    "https://hooks.bolna.ai/callbacks/{slug}",
    data=body,
    headers={"Content-Type": "application/json", "X-Bolna-Signature": f"sha256={sig}"},
)
```

With **Require signature** off, a request without the header is accepted, but one that carries a wrong `X-Bolna-Signature` is still rejected with `401`.

***

## Outputs

When the execution resumes, the node writes `callback.*` variables and its cases branch on them:

* `callback.status` — `received` when a matching request resumed the execution, or `timeout` when `timeout_s` elapsed first.
* `callback.<name>` — every `payload_map` entry. Only scalar values are kept, so map leaf fields rather than whole objects. A path that is missing from the body, or that lands on an object or array, is omitted with a warning rather than set. Strings are truncated at 1024 characters.
* `node.<node_id>.callback.*` — a durable copy of `callback.status` and each mapped value, readable after a later callback node has cleared `callback.*`.

A timeout sets only `callback.status`, so no mapped values exist on that path. `node.<node_id>.callback.status` is recorded on a timeout too.

> [!NOTE]
>
> Every callback node must route its timeout explicitly. When you place the node, the editor adds a locked **Timed out** condition, `callback.status == "timeout"`. Connect its exit to the node a timed-out contact should go to. Left unconnected, it doesn't count. Publishing fails with `callback_timeout_unrouted` when no case covers the timeout and the node has no `on_no_match` of its own. The definition-wide `on_no_match` does not count.

Bolna keeps only the mapped values. The raw body is held for 30 minutes so **Wait for a test event** and the [Get Last Callback API](https://www.bolna.ai/docs/api-reference/workflows/get-last-callback.md) can show it, then discarded.

***

## Example

This node waits up to two days for a signed version of the payment request shown above. `lead.phone` matches the contact's `entry.mobile_number`, so `callback.payment_id` becomes `pay_29QQoUBi66xm2f` and `callback.amount` becomes `4999`. A full payment ends the journey as paid, a timeout moves on to a reminder call, and a short payment falls through to `on_no_match` for review.

```json theme={"system"}
{
  "id": "n_wait_payment",
  "type": "callback",
  "name": "Wait for payment",
  "config": {
    "timeout_s": 172800,
    "correlation": { "payload_path": "lead.phone", "matches": "entry.mobile_number" },
    "payload_map": { "payment_id": "payment.id", "amount": "payment.amount" },
    "require_signature": true
  },
  "on_no_match": "n_end_review",
  "cases": [
    { "when": { "all": [
        { "cmp": "==", "left": { "var": "callback.status" }, "right": { "const": "received" } },
        { "cmp": ">=", "left": { "var": "callback.amount" }, "right": { "const": 4999 } }
      ] },
      "then": { "to": "n_end_paid" } },
    { "when": { "cmp": "==", "left": { "var": "callback.status" }, "right": { "const": "timeout" } },
      "then": { "to": "n_reminder_call" } }
  ]
}
```

***

## Next steps

> [card] [Nodes](https://www.bolna.ai/docs/workflows/nodes.md)
>
> Every node type with its configuration and examples

> [card] [Conditions and variables](https://www.bolna.ai/docs/workflows/conditions-and-variables.md)
>
> The expression language cases are written in


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.