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
Addcallback_url to POST /chat. Combined with wait=false and an idempotency_key, the request returns at once and is safe to retry:
Which addresses are accepted
- The address must use
httpsand resolve to public addresses only. It is checked again before every delivery. - The deployment must have a webhook signing secret. Without one, every
callback_urlis 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_urlis refused. - SaaS: any public
httpshost, by default.
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.
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
2xxor3xxcounts as delivered. - A
4xxis 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.
run_id, event and status, so a retry after a slow answer does nothing twice.
Verify every delivery
Each POST carries these headers: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:
- Recompute the signature over the raw body, exactly as received, and compare it in constant time.
- Reject a delivery whose timestamp is more than 5 minutes from your clock.
- Reject a delivery whose
X-NF-Delivery-Idyou have already seen.