Skip to main content
Webhooks let you subscribe to events in Orq.ai and receive an HTTP POST request to your server whenever those events occur, with no polling required.

Setting Up a Webhook

Navigate to Settings → Project → Webhooks and click Webhook to configure the following:
  • Name: a unique name to identify this webhook
  • URL: the endpoint on your server that will receive the HTTP POST requests
  • Enable webhook: controls whether this endpoint receives deliveries
  • Event types: choose which events should trigger this webhook
Select Create webhook to create the endpoint.
Create webhook endpoint sheet with Name, URL, Enable webhook, and Event types
fields

Create a webhook endpoint with a name, URL, the Enable webhook switch, and event types.

When deployment events are selected, choose Send me everything or Select individual deployments. Both are stored in events, and POST /v2/webhooks takes the same form; there is no separate deployment field.For example, ["deployment.created", "deployment.invoked.01kkypj82sqrzg1s9t9v9p13jv"] delivers invocations for that deployment only.
After adding the webhook, a Save your signing secret dialog appears with the secret, which is not shown again. To replace a lost secret, generate a new one with GET /v2/webhooks/secret and send it in a PATCH /v2/webhooks/{id} body. The webhook keeps its ID and event subscriptions.
A webhook is scoped to the workspace: one webhook receives events from every project in the workspace. Use the signing secret to verify incoming requests.

Event Types

Orq.ai sends webhooks for the following events, grouped by resource:

Delivery

Orq.ai sends each matching event as an HTTP POST to the endpoint URL, with the event JSON as the body. A delivery succeeds when the endpoint responds with any 2xx status within 15 seconds.
The body is JSON for both content_type values. Choosing application/x-www-form-urlencoded sets the Content-Type header only, so a receiver that branches on that header has to parse the body as JSON: with Express, express.json() skips it and express.text({ type: "*/*" }) then JSON.parse reads it.
  • Timeout: the request is abandoned after 15 seconds and the delivery counts as failed. Connecting to the endpoint allows 5 seconds, and response headers must arrive within 10 seconds.
  • Retries: a failed delivery is attempted twice more, 5 seconds after the first failure and 10 seconds after the second, for three attempts in total. After the third failed attempt the event is not delivered again.
  • No retry: 4xx responses are permanent except 408, 409, 425, and 429. Those four, 5xx responses, timeouts, and connection failures are retried.
  • Identical retries: every attempt for the same event and endpoint sends the same body, the same X-Orq-Signature, and the same Idempotency-Key header.

Failed deliveries

Each webhook carries failure_count, the number of consecutive failed attempts, and enabled, which turns delivery off. Re-enable a disabled webhook by patching enabled to true, which also resets failure_count to 0. Events dropped while it was disabled are not replayed.

Replay Protection

The signature covers the request body only and includes no timestamp, so a captured request remains verifiable indefinitely when replayed to the endpoint. Defend on the receiver side:
  • Deduplicate: store delivered event id values, or the Idempotency-Key header, and discard repeats. The Idempotency-Key value is stable for the same event and endpoint, so retries and replays of one delivery carry the same key. The event id is also sent as X-Orq-Hook-ID.
  • Reject stale events: after verifying the signature, compare the created timestamp in the body with the current time and drop events older than the tolerated window.

Create errors

_id is a client-generated string of at least one character with no fixed format, and uniqueness is collection-wide, not per workspace.

Delivery Metrics

Webhooks dashboard showing delivery metrics, event deliveries chart,
response time chart, and endpoint list

The Webhooks page showing delivery metrics and endpoint list.

The Webhooks page shows a Delivery Metrics dashboard with:
  • Total Deliveries, Successful, Failed, and Avg Duration over a configurable time range
  • An Event deliveries chart showing successful vs. failed deliveries over time
  • A Response time chart showing min, avg, and max response times
Each webhook endpoint is listed with its name, URL, event types, and status, plus a truncated signing secret. The full secret is shown once, when the webhook is created.

Payload Structure

The body is built when the event is recorded, not when it is delivered. An LLM event carries gen_ai.input and gen_ai.output exactly as they were recorded. Masking happens at ingest, before any sink runs, so a masked trace is delivered masked. An LLM event whose body exceeds 10,240,000 bytes (about 9.77 MiB) is not published and never reaches an endpoint. Events share the envelope keys below, with the exceptions each group notes. Three groups differ in how created and id are written. request_id identifies the originating API request and is absent for system-initiated events.

Agent

Deployment

Unlike CRUD events, deployment.invoked does not include workspace, project, api_version, or correlation_id. Deployment metadata is provided in a top-level metadata block instead of a nested object.
status is always present. It contains the HTTP status code returned by the upstream model provider (e.g. 200, 429, 500), useful for detecting partial failures without inspecting the full response.Several other fields are conditional and may be absent depending on the invocation:
  • contact_id: present when an Identity is linked to the request
  • billing: omitted when the response was served from cache
  • cache_status, cache_key, cache_config: present on cached responses
  • evals: present when Evaluators are configured on the deployment
  • thread: present when the invocation is part of a thread

Prompt

LLM

LLM events fire after the gateway processes a chat completion, response, embedding, or rerank call. llm.evaluator fires when an Evaluator finishes running. The data block carries the OpenTelemetry GenAI semantic-convention span attributes so subscribers receive the full request and response payload inline. For the full list of orq.* attributes in the payload, see Span Attributes.
LLM events are only sent while Tracing Enabled is on in General Settings. New workspaces start with tracing off.
The wire shape of gen_ai.input and gen_ai.output depends on which producer emitted the span:
  • For Responses API spans (llm.response), the canonical input/output is on openresponses.input / openresponses.output and is delivered as a JSON-encoded string.
  • For chat completion / embedding / rerank spans, the canonical fields follow OTEL GenAI semconv: gen_ai.input.messages / gen_ai.output.messages (chat), gen_ai.rerank.query / gen_ai.rerank.results (rerank).
  • For evaluator spans (llm.evaluator), the evaluated data is on orq.evaluation.input and the result on orq.evaluation.output, both delivered as JSON-encoded strings.
  • The envelope’s top-level project field is omitted when the span has no associated project.

Best Practices

  • Use HTTPS: always use HTTPS for your webhook URL to ensure payloads are transmitted securely.
  • Verify signatures: validate the X-Orq-Signature header on every request before processing the payload.
  • Respond quickly: acknowledge receipt immediately with a 200 response. Offload any heavy processing to a background job.
  • Handle retries: if your endpoint is temporarily unavailable, Orq.ai may retry delivery. Make your handler idempotent using the event id to avoid processing the same event twice.
  • Monitor delivery: use the Delivery Metrics dashboard to track failures and response times.

Security

Every webhook request includes a signature you should verify before processing the payload.

Headers

How the signature is computed

The signature is computed over the exact raw request body bytes sent by Orq.ai. Verify the signature before parsing or modifying the body. Parsing and re-serializing JSON can change whitespace, field order, or number formatting and produce an invalid signature.
This is signed with your webhook secret using HMAC-SHA256 and hex-encoded. Always use constant-time string comparison to prevent timing attacks.

Verification examples