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 Then save the definition with the Save Draft API. A completed call moves to the callback node, The Timed out case is required. Publishing fails with
0.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.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.The
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: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 theidwhen you edit the node. A node with a newidgets a new URL. - Changing
correlationin 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. Changingpayload_maponly 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