How webhooks work
- You configure a webhook URL and secret on a project.
- Whenever a reviewer submits a verdict in the review workspace —
approve,reject, orcorrect— Tuor enqueues a background job. - The background task dispatches an HTTP
POSTrequest asynchronously to the configured URL with a JSON body and signature headers. - Delivery status is recorded in Tuor and can be inspected from the Web Console.
Configure a webhook
Configure the webhook URL and secret from the Webhook section on the project’s Config tab in the Web Console. The URL must be a publicly reachablehttps:// address, and the secret must be at least 16 characters.
Send a test event from the same section, or with POST /v1/projects/{project_id}/test-webhook, to check your receiver.
Tying webhook events back to your system (the traceback loop)
A webhook payload is the same publicTraceEventResponse event object returned in trace detail timelines, so it carries the Tuor trace_id (also sent in the X-Tuor-Trace-Id header) but not the trace’s spans / trace_config / model_output. Map deliveries back to your own rows by storing the trace_id you receive at ingest time.
1. Record the trace id at ingest time
Creating a trace returns its Tuorid. Persist it against your own row:
2. Look up the row when the webhook arrives
event_type) and authoritative output (final_output_after) are in the event itself, so the common case needs no callback.
Payload structure
Every webhook delivery uses the same publicTraceEventResponse shape returned in trace detail timelines. Datetimes are ISO 8601 strings, and enum values are plain strings:
trace_id to link back to the trace — but not the trace’s static fields (spans, model_output, trace_config, output_schema). Fetch GET /v1/traces/{trace_id} if a receiver needs the full canonical trace object.
webhook.test payloads are a separate, smaller shape: they include event_type (webhook.test), action, occurred_at, and project. A test ping has no real event or trace, so it carries no id and its X-Tuor-Event-Id / X-Tuor-Trace-Id headers are blank.
Field reference
Event types
Only review outcomes produce webhook deliveries. Resets, deletes, restores, and tag changes don’t call your webhook.
Request headers
Every webhook request includes:Signature verification
Always verify the signature before trusting a webhook body. Tuor signs the raw request body bytes with HMAC-SHA256 using thewebhook_secret you configured on the project.
Use a constant-time comparison; never compare hex strings with == in user code.
Python
TypeScript
Complete raw-body handlers
Mount the raw-body webhook route before any global JSON parser middleware.Delivery semantics
- Asynchronous: review API calls return as soon as the trace is saved; webhooks fire shortly after.
- Timeout: 10 seconds per attempt. Any
2xxresponse counts as delivered; anything else is a failure. - One automatic retry: if Tuor can’t reach your server at all, it tries once more a second later. Once your server responds, with any status, that response is final.
- Manual retries: a failed delivery stays failed until you retry it from the Webhook section in the Web Console, or with the API.
If your setup needs delivery guarantees beyond these, get in touch.
Receiver checklist
- Listen on a stable, publicly routable HTTPS URL.
- Respond with
2xxonly after you’ve durably stored the event (or are sure you can drop it). - Verify
X-Tuor-Signatureon every request — constant-time compare. - Deduplicate on the event
id(or theX-Tuor-Event-Idheader). Retries reuse the sameid. - Process within 10 seconds; for heavy work, hand off to your own background queue and return immediately.
- Handle
webhook.testevents gracefully — they carry no trace data and identify the project being tested.