> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralfactory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive a signed POST on your server when a run ends or pauses, and verify it.

A webhook lets your server hear about a run instead of polling it. You pass a `callback_url` when you start the run, and the platform POSTs to it when the run ends and each time it pauses for a person.

## Ask for a webhook

Add `callback_url` to `POST /chat`. Combined with `wait=false` and an `idempotency_key`, the request returns at once and is safe to retry:

```bash theme={null}
curl -X POST https://api.neuralfactory.ai/chat \
  -H "Authorization: Bearer $NF_TOKEN" \
  -F "agent_id=$AGENT_ID" \
  -F "message=Draft the Q3 board summary" \
  -F "wait=false" \
  -F "idempotency_key=board-summary-2026-q3" \
  -F "callback_url=https://example.com/hooks/neuralfactory"
```

### Which addresses are accepted

* The address must use `https` and resolve to public addresses only. It is checked again before every delivery.
* The deployment must have a webhook signing secret. Without one, every `callback_url` is refused.
* **Enterprise**: the host must be on the deployment's webhook allow list. A listed domain also allows its subdomains. With no list, every `callback_url` is refused.
* **SaaS**: any public `https` host, by default.

A refused address answers `400`, with the reason in `detail`.

## The events

The platform POSTs when the run ends (`completed`, `failed`, `cancelled`, `timed_out`) and each time it pauses (`awaiting_input`). Each event is sent once per state; a new pause with different pending requests is a new event.

```json theme={null}
{
  "event": "agent_run.terminal",
  "run_id": "…",
  "chat_id": "…",
  "agent_id": "…",
  "status": "completed",
  "record_id": "…",
  "error": null,
  "cost": { "total_cost": 0.0123 },
  "interrupts": [],
  "ts": "2026-07-22T10:00:00Z"
}
```

| Field | Meaning |
| - | - |
| `event` | `agent_run.awaiting_input` when the run paused, otherwise `agent_run.terminal` |
| `run_id`, `chat_id`, `agent_id` | Identifiers |
| `status` | The run's status at the time of the event |
| `record_id` | The interaction record of the turn |
| `error` | Why the run ended, when it failed or timed out |
| `cost` | What the run cost |
| `interrupts` | The pending requests for a person, on an `awaiting_input` event |
| `ts` | When the event was built |

The event does not carry the answer. Fetch it with `GET /runs/{run_id}`: the text is in `result.result`.

## Delivery and retries

* Your endpoint has 10 seconds to answer.
* Any `2xx` or `3xx` counts as delivered.
* A `4xx` is taken as your decision and is not retried.
* A `5xx`, a timeout or a network error is retried with growing pauses: 30 seconds, then 1, 2 and 4 minutes and so on, up to 8 attempts over about an hour.
* An address that no longer passes the checks above at delivery time is not sent to, and not retried.
* Delivery never affects the run.

A retry sends the same body. Process each event once, keyed on `run_id`, `event` and `status`, so a retry after a slow answer does nothing twice.

## Verify every delivery

Each POST carries these headers:

```
X-NF-Event: agent-run
X-NF-Event-Version: 1
X-NF-Timestamp: <unix seconds>
X-NF-Delivery-Id: <unique per attempt>
X-NF-Signature: sha256=<hex>
```

The signature is `HMAC-SHA256(secret, timestamp + "." + raw_body)` in hex, where `timestamp` is the `X-NF-Timestamp` value and `secret` is the deployment's webhook signing secret. To accept a delivery:

1. Recompute the signature over the raw body, exactly as received, and compare it in constant time.
2. Reject a delivery whose timestamp is more than 5 minutes from your clock.
3. Reject a delivery whose `X-NF-Delivery-Id` you have already seen.

```python theme={null}
import hashlib, hmac, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    timestamp = headers["X-NF-Timestamp"]
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, headers["X-NF-Signature"]):
        return False
    return abs(time.time() - int(timestamp)) <= 300
```

The signing secret belongs to the deployment, not to an API key. On Enterprise, your administrator configures it. On SaaS, [contact Neural Factory](https://docs.neuralfactory.ai/help/contact.md) for it.

## Related

* [Runs and results](https://docs.neuralfactory.ai/api-reference/runs.md)
* [Streaming](https://docs.neuralfactory.ai/api-reference/streaming.md)
* [Errors](https://docs.neuralfactory.ai/api-reference/errors.md)


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