Skip to main content

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.

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 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, 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".
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.
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.
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.
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 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.

Next steps

Nodes

Every node type with its configuration and examples

Conditions and variables

The expression language cases are written in