Skip to main content
Webhooks let your systems react to reviewer verdicts in real time — for example, updating a record the instant a reviewer corrects a model output, or paging an on-call engineer when a critical trace is rejected. This page covers receiver setup, payload shape, signature verification, and delivery semantics.

How webhooks work

  1. You configure a webhook URL and secret on a project.
  2. Whenever a reviewer submits a verdict in the review workspace — approve, reject, or correct — Tuor enqueues a background job.
  3. The background task dispatches an HTTP POST request asynchronously to the configured URL with a JSON body and signature headers.
  4. 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 reachable https:// 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 public TraceEventResponse 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 Tuor id. Persist it against your own row:

2. Look up the row when the webhook arrives

The verdict (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 public TraceEventResponse shape returned in trace detail timelines. Datetimes are ISO 8601 strings, and enum values are plain strings:
The payload carries the event and its before/after deltas, plus 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 the webhook_secret you configured on the project. Use a constant-time comparison; never compare hex strings with == in user code.

Python

TypeScript

Signatures are computed over the raw bytes of the request body, before any JSON parsing. Frameworks that re-serialize the body will produce a different digest. In Express, use express.raw({ type: "application/json" }) on the webhook route; in FastAPI, read await request.body() before parsing.

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 2xx response 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 2xx only after you’ve durably stored the event (or are sure you can drop it).
  • Verify X-Tuor-Signature on every request — constant-time compare.
  • Deduplicate on the event id (or the X-Tuor-Event-Id header). Retries reuse the same id.
  • Process within 10 seconds; for heavy work, hand off to your own background queue and return immediately.
  • Handle webhook.test events gracefully — they carry no trace data and identify the project being tested.