> ## 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.

# Pause a journey until your system responds

> Build a workflow that calls a contact, waits for your system to confirm a payment via the callback node, and reads the result using only the Bolna API and curl.

The whole integration is three calls on your side. You fetch the [callback node](https://www.bolna.ai/docs/workflows/callback.md)'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`.

```mermaid theme={"system"}
sequenceDiagram
    participant S as Your system
    participant B as Bolna
    participant C as Contact
    S->>B: Fetch the callback URL and signing secret
    S->>B: Run the workflow for a contact
    B->>C: Agent call
    Note over B: Execution waits at n_wait_payment
    C->>S: Pays
    S->>B: Signed POST to the callback URL
    B-->>S: 202, match "matched"
    Note over B: Received case, ends at n_end_paid
    S->>B: Read the execution
    B-->>S: callback.status and mapped values
```

**1. Create the workflow and save its definition**

Create the workflow with the [Create Workflow API](https://www.bolna.ai/docs/api-reference/workflows/create.md). It starts with an empty draft at revision `0`.

```bash request theme={"system"}
curl --location 'https://api.bolna.ai/workflows' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data '{ "name": "Payment follow-up" }'
```

```json response theme={"system"}
{
  "id": "1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708",
  "name": "Payment follow-up",
  "status": "active",
  "latest_published_version": null
}
```

Then save the definition with the [Save Draft API](https://www.bolna.ai/docs/api-reference/workflows/save-draft.md). 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`.

```bash request theme={"system"}
curl --location --request PUT 'https://api.bolna.ai/workflows/1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708/draft' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "expected_revision": 0,
  "definition": {
    "entry_node_id": "n_start",
    "on_no_match": "n_end_unpaid",
    "nodes": [
      {
        "id": "n_start",
        "type": "start",
        "config": { "trigger": { "kind": "manual" } },
        "cases": [ { "when": { "always": true }, "then": { "to": "n_call" } } ]
      },
      {
        "id": "n_call",
        "type": "agent",
        "name": "Payment reminder",
        "config": { "agent_id": "<agent_id>" },
        "cases": [
          { "when": { "cmp": "==", "left": { "var": "call.status" }, "right": { "const": "completed" } },
            "then": { "to": "n_wait_payment" } }
        ]
      },
      {
        "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
        },
        "cases": [
          { "when": { "cmp": "==", "left": { "var": "callback.status" }, "right": { "const": "received" } },
            "then": { "to": "n_end_paid" } },
          { "when": { "cmp": "==", "left": { "var": "callback.status" }, "right": { "const": "timeout" } },
            "then": { "to": "n_end_unpaid" } }
        ]
      },
      { "id": "n_end_paid", "type": "end", "config": { "label": "paid", "outcome": "success" } },
      { "id": "n_end_unpaid", "type": "end", "config": { "label": "unpaid", "outcome": "failure" } }
    ]
  }
}'
```

```json response theme={"system"}
{
  "revision": 1
}
```

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](https://www.bolna.ai/docs/workflows/callback.md#example).

**2. Publish**

Freeze the draft as version 1 with the [Publish API](https://www.bolna.ai/docs/api-reference/workflows/publish.md). The callback URL only resumes executions once the node is in a published version.

```bash request theme={"system"}
curl --location --request POST 'https://api.bolna.ai/workflows/1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708/publish' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data '{}'
```

```json response theme={"system"}
{
  "version": 1,
  "published_at": "2026-10-14T10:05:00Z",
  "warnings": []
}
```

**3. Fetch the callback URL**

Read the node's URL and signing secret with the [Get Callback URL API](https://www.bolna.ai/docs/api-reference/workflows/get-callback.md). Store both in your system. The URL stays the same while the node keeps its id.

```bash request theme={"system"}
curl --location 'https://api.bolna.ai/workflows/1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708/nodes/n_wait_payment/callback' \
--header 'Authorization: Bearer <api_key>'
```

```json response theme={"system"}
{
  "url": "https://hooks.bolna.ai/callbacks/Zr0x3M5uQ8lA2wq7Yb1nC4dE6fG9hJkL",
  "slug": "Zr0x3M5uQ8lA2wq7Yb1nC4dE6fG9hJkL",
  "signing_secret": "9b1f0c7e5a3d2b4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d",
  "created_at": "2026-10-14T10:00:00Z",
  "rate_limit_per_min": null
}
```

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](https://www.bolna.ai/docs/api-reference/workflows/run.md). This places a real call.

```bash request theme={"system"}
curl --location 'https://api.bolna.ai/workflows/1f2a3b4c-5d6e-7f80-91a2-b3c4d5e6f708/run' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "reference_id": "lead_10442",
  "mobile_number": "+919876543210",
  "name": "Asha"
}'
```

```json response theme={"system"}
{
  "execution_id": "exec:9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4:lead_10442",
  "campaign_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
  "workflow_version": 1,
  "status": "pending"
}
```

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.

```bash request theme={"system"}
SIGNING_SECRET='9b1f0c7e5a3d2b4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d'   # signing_secret from step 3
BODY='{"event":"payment.captured","lead":{"phone":"+919876543210"},"payment":{"id":"pay_29QQoUBi66xm2f","amount":4999,"currency":"INR"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | sed 's/^.* //')

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

```json response theme={"system"}
{
  "status": "accepted",
  "match": "matched"
}
```

`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](https://www.bolna.ai/docs/api-reference/workflow-executions/get.md):

```bash request theme={"system"}
curl --location 'https://api.bolna.ai/workflow-executions/exec%3A9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4%3Alead_10442' \
--header 'Authorization: Bearer <api_key>'
```

```json response theme={"system"}
{
  "id": "exec:9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4:lead_10442",
  "status": "completed",
  "current_node_id": "n_end_paid",
  "termination_reason": "paid",
  "outcome": "success",
  "nodes": [
    { "node_id": "n_start", "node_type": "start", "attempt": 1, "status": "completed", "matched_case_index": 0, "to_node_id": "n_call" },
    { "node_id": "n_call", "node_type": "agent", "attempt": 1, "status": "completed", "matched_case_index": 0, "to_node_id": "n_wait_payment",
      "outputs": { "call.status": "completed", "call.duration_s": 74 } },
    { "node_id": "n_wait_payment", "node_type": "callback", "attempt": 1, "status": "completed", "matched_case_index": 0, "to_node_id": "n_end_paid",
      "outputs": { "callback.status": "received", "callback.payment_id": "pay_29QQoUBi66xm2f", "callback.amount": 4999 } },
    { "node_id": "n_end_paid", "node_type": "end", "attempt": 1, "status": "completed", "to_node_id": null }
  ]
}
```

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

| Status | Meaning | What to do |
| - | - | - |
| `202` | Accepted. `match` is `matched` when a waiting execution took the request, and `none` when nothing was waiting, it was already resumed, or the URL was revoked within the last 7 days | Treat as delivered |
| `400` | The body is not valid JSON | Fix the body. Don't retry |
| `401` | `X-Bolna-Signature` is wrong, or missing while **Require signature** is on | Fix the signing. Don't retry |
| `404` | Unknown URL, or one revoked more than 7 days ago | Fetch the node's current URL. Don't retry |
| `413` | The body is larger than 256 KB | Send only the fields you map. Don't retry |
| `415` | `Content-Type` is not `application/json` or another `application/*+json` type | Set the header. Don't retry |
| `429` | Over the URL's budget of 1000 requests per minute by default | Retry after `Retry-After` |
| `503` | Bolna could not durably accept the request yet | Retry after `Retry-After`, with backoff |

***

## Changing a published workflow

* **Campaigns pin a version.** A [campaign](https://www.bolna.ai/docs/workflows/campaigns.md) 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

> [card] [Callback node](https://www.bolna.ai/docs/workflows/callback.md)
>
> Correlation, signing, outputs and the full request contract

> [card] [Execution webhook](https://www.bolna.ai/docs/workflows/execution-webhook)
>
> Get one POST when each execution finishes, instead of polling


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