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. Atime 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
202for 7 days so your retries don’t error, then404. 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_sbelow.
- 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_mapentry and acallback.<name>variable. - Next-case preview — shows which case the node would take for the sample body.
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".
Matching a request to a contact
Every request has to say which contact it is about. The node reads the value atcorrelation.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_numberand any field declaredphone. Spaces, dashes and parentheses are ignored, and a number without a country code is read as an Indian (+91) number.9876543210,09876543210,0091 98765-43210and+91 98765-43210all match+919876543210. Sending the full international form is still the safest. - Other declared fields are coerced to their type first. For a
numberfield,00123matches123and1001.0matches1001. A field declaredemailignores case, soAsha@Example.commatchesasha@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
timeoutbranch at once, with amissing_correlation_valuewarning 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 aPOST 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 anX-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.
X-Bolna-Signature is still rejected with 401.
Outputs
When the execution resumes, the node writescallback.* variables and its cases branch on them:
callback.status—receivedwhen a matching request resumed the execution, ortimeoutwhentimeout_selapsed first.callback.<name>— everypayload_mapentry. 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 ofcallback.statusand each mapped value, readable after a later callback node has clearedcallback.*.
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.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