Skip to main content
The whole integration is three calls on your side. You fetch the callback node’s URL once, POST to it when the event happens in your system, and read the execution to see where the contact went. This guide builds the workflow around them with curl: Bolna calls a contact about a payment, waits up to two days for your system to report it, and ends the journey as paid or unpaid. You need a Bolna API key and an agent_id.
1

Create the workflow and save its definition

Create the workflow with the Create Workflow API. It starts with an empty draft at revision 0.
Then save the definition with the Save Draft API. A completed call moves to the callback node, n_wait_payment. Its Received case ends the journey as paid and its Timed out case as unpaid. A call that doesn’t complete falls through to the definition-wide on_no_match, which is also unpaid.
The Timed out case is required. Publishing fails with callback_timeout_unrouted when no case covers the timeout and the node has no on_no_match of its own. To branch on what your system sends, add conditions on callback.amount or callback.payment_id to the Received case, as in the callback node example.
2

Publish

Freeze the draft as version 1 with the Publish API. The callback URL only resumes executions once the node is in a published version.
3

Fetch the callback URL

Read the node’s URL and signing secret with the Get Callback URL API. Store both in your system. The URL stays the same while the node keeps its id.
The signing secret is the literal ASCII key for the signature. Don’t hex-decode it.
4

Run a contact

Start a run with the Run Workflow API. This places a real call.
Events that arrive before the execution reaches the callback node are not buffered. When testing by hand, read the execution as in the next step and wait until its current_node_id is n_wait_payment before you POST.
5

Send the event and read the result

When the payment lands, POST it to the callback URL. Sign the exact bytes you send with the signing secret, because the node requires a signature.
match is matched when the waiting execution took the request. lead.phone matched the contact’s entry.mobile_number, so the execution resumed through its Received case. Read it with the Get Execution API:
The n_wait_payment entry holds the callback node’s outputs: callback.status is received, and each payload_map name carries the value your system sent. Had the two days passed first, callback.status would be timeout and the contact would have ended at n_end_unpaid.

What the status codes mean for your retry logic


Changing a published workflow

  • Campaigns pin a version. A campaign keeps running the version it was created with after you publish again, while a new single run uses the latest published version.
  • The URL is keyed by the node’s id, so it survives renames and republishes. Keep the id when you edit the node. A node with a new id gets a new URL.
  • Changing correlation in a new version does not strand executions waiting on an older one. A POST is matched using the correlation settings of every published version still pinned by a campaign that hasn’t completed or been aborted, so both the old and the new body shape resume their own executions until those campaigns finish. Changing payload_map only affects executions on the new version.
  • Removing the node keeps its URL live while a campaign that hasn’t completed or been aborted still runs a version containing it. The first publish after the last such campaign finishes revokes it, and an execution still waiting at the node then ends in timeout.

Next steps

Callback node

Correlation, signing, outputs and the full request contract

Execution webhook

Get one POST when each execution finishes, instead of polling