Skip to main content
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:

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.
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:
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.
The signing secret belongs to the deployment, not to an API key. On Enterprise, your administrator configures it. On SaaS, contact Neural Factory for it.