Subscribe to Orq.ai events and receive real-time HTTP POST notifications when agents, deployments, prompts, and other resources change.
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
AI Studio
API & SDK
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 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.
Option
Stored in events
Send me everything
deployment.invoked
Select individual deployments
One deployment.invoked.<deployment_id> per selected deployment
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.
Create webhooks programmatically in two calls:
Generate a signing secret with GET /v2/webhooks/secret. The response returns the value in a secret field. The secret is not stored until a webhook is created with it.
Create the webhook with POST /v2/webhooks, sending that secret in the body.
Required fields
Field
Description
_id
Client-generated webhook ID.
url
HTTPS endpoint that receives deliveries.
content_type
application/json or application/x-www-form-urlencoded. The body is JSON either way; see Delivery.
display_name
Human-readable webhook name.
events
One or more event slugs from Event Types, for example deployment.invoked.
secret
The signing secret from step 1.
enabled is optional. Omitting it leaves deliveries enabled.
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:
Group
Event
Agent
agent.created
agent.updated
agent.deleted
Deployment
deployment.created
deployment.updated
deployment.deleted
deployment.invoked
Prompt
prompt.created
prompt.updated
prompt.deleted
LLM
llm.chat_completion
llm.response
llm.embedding
llm.rerank
llm.evaluator
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.
Event
Result
Any delivery succeeds
failure_count resets to 0
An attempt fails
failure_count increases by 1, so one failed delivery adds up to 3
The tenth consecutive failed attempt
The webhook is disabled
A 401 or 403 response
The webhook is disabled at once, because the endpoint rejected the credentials
A third failed attempt for one event
That event is dropped; later events still deliver
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.
Accepted and stored; it delivers only if an event carries that slug, as deployment.invoked.<deployment_id> does
_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
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.
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
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 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.
{ "id": "evt_194c87ee3cee419a20ccd730a7", "object": "event", "type": "llm.rerank", "created": 1778437606, "api_version": "1.0", "workspace": "3de3a12f-6c52-46b5-a195-539bc40e99c9", "correlation_id": "1c1aa12dad4675fbdf673dfcd41c53d1", "data": { "span_id": "919ab2e33d8e838e", "trace_id": "1c1aa12dad4675fbdf673dfcd41c53d1", "parent_span_id": "c40e7f287a267c29", "span_type": "span.rerank", "name": "rerank jina-reranker-v2-base-multilingual", "start_time": "2026-05-10T18:26:45.708812Z", "end_time": "2026-05-10T18:26:45.710460167Z", "duration_ns": 1648167, "status": "OK", "attributes": { "gen_ai.operation.name": "rerank", "gen_ai.output.count": 3, "gen_ai.provider.name": "jina", "gen_ai.request.model": "jina-reranker-v2-base-multilingual", "gen_ai.request.top_n": 3, "gen_ai.rerank.documents": "[\"Organic skincare for sensitive skin with aloe vera and chamomile: Imagine the soothing embrace of nature with our organic skincare range, crafted specifically for sensitive skin. Infused with the calming properties of aloe vera and chamomile, each product provides gentle nourishment and protection. Say goodbye to irritation and hello to a glowing, healthy complexion.\",\"New makeup trends focus on bold colors and innovative techniques: Step into the world of cutting-edge beauty with this seasons makeup trends. Bold, vibrant colors and groundbreaking techniques are redefining the art of makeup. From neon eyeliners to holographic highlighters, unleash your creativity and make a statement with every look.\",\"Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille: Erleben Sie die wohltuende Wirkung unserer Bio-Hautpflege, speziell für empfindliche Haut entwickelt. Mit den beruhigenden Eigenschaften von Aloe Vera und Kamille pflegen und schützen unsere Produkte Ihre Haut auf natürliche Weise. Verabschieden Sie sich von Hautirritationen und genießen Sie einen strahlenden Teint.\",\"Neue Make-up-Trends setzen auf kräftige Farben und innovative Techniken: Tauchen Sie ein in die Welt der modernen Schönheit mit den neuesten Make-up-Trends. Kräftige, lebendige Farben und innovative Techniken setzen neue Maßstäbe. Von auffälligen Eyelinern bis hin zu holografischen Highlightern – lassen Sie Ihrer Kreativität freien Lauf und setzen Sie jedes Mal ein Statement.\",\"Cuidado de la piel orgánico para piel sensible con aloe vera y manzanilla: Descubre el poder de la naturaleza con nuestra línea de cuidado de la piel orgánico, diseñada especialmente para pieles sensibles. Enriquecidos con aloe vera y manzanilla, estos productos ofrecen una hidratación y protección suave. Despídete de las irritaciones y saluda a una piel radiante y saludable.\",\"Las nuevas tendencias de maquillaje se centran en colores vivos y técnicas innovadoras: Entra en el fascinante mundo del maquillaje con las tendencias más actuales. Colores vivos y técnicas innovadoras están revolucionando el arte del maquillaje. Desde delineadores neón hasta iluminadores holográficos, desata tu creatividad y destaca en cada look.\",\"针对敏感肌专门设计的天然有机护肤产品:体验由芦荟和洋甘菊提取物带来的自然呵护。我们的护肤产品特别为敏感肌设计,温和滋润,保护您的肌肤不受刺激。让您的肌肤告别不适,迎来健康光彩。\",\"新的化妆趋势注重鲜艳的颜色和创新的技巧:进入化妆艺术的新纪元,本季的化妆趋势以大胆的颜色和创新的技巧为主。无论是霓虹眼线还是全息高光,每一款妆容都能让您脱颖而出,展现独特魅力。\",\"敏感肌のために特別に設計された天然有機スキンケア製品: アロエベラとカモミールのやさしい力で、自然の抱擁を感じてください。敏感肌用に特別に設計された私たちのスキンケア製品は、肌に優しく栄養を与え、保護します。肌トラブルにさようなら、輝く健康な肌にこんにちは。\",\"新しいメイクのトレンドは鮮やかな色と革新的な技術に焦点を当てています: 今シーズンのメイクアップトレンドは、大胆な色彩と革新的な技術に注目しています。ネオンアイライナーからホログラフィックハイライターまで、クリエイティビティを解き放ち、毎回ユニークなルックを演出しましょう。\"]", "gen_ai.rerank.documents.count": 10, "gen_ai.rerank.query": "Organic skincare products for sensitive skin", "gen_ai.rerank.results": "[{\"_id\":\"rerank_01kr9j8jae2zxygmftpz9880wc\",\"kind\":\"rerank\",\"index\":0,\"relevance_score\":0.87831426,\"document\":\"Organic skincare for sensitive skin with aloe vera and chamomile: Imagine the soothing embrace of nature with our organic skincare range, crafted specifically for sensitive skin. Infused with the calming properties of aloe vera and chamomile, each product provides gentle nourishment and protection. Say goodbye to irritation and hello to a glowing, healthy complexion.\"},{\"_id\":\"rerank_01kr9j8jae611fg8mqn8dm08y5\",\"kind\":\"rerank\",\"index\":6,\"relevance_score\":0.87747681,\"document\":\"针对敏感肌专门设计的天然有机护肤产品:体验由芦荟和洋甘菊提取物带来的自然呵护。我们的护肤产品特别为敏感肌设计,温和滋润,保护您的肌肤不受刺激。让您的肌肤告别不适,迎来健康光彩。\"},{\"_id\":\"rerank_01kr9j8jaetc7rzkrqkjse3pbh\",\"kind\":\"rerank\",\"index\":4,\"relevance_score\":0.86246759,\"document\":\"Cuidado de la piel orgánico para piel sensible con aloe vera y manzanilla: Descubre el poder de la naturaleza con nuestra línea de cuidado de la piel orgánico, diseñada especialmente para pieles sensibles. Enriquecidos con aloe vera y manzanilla, estos productos ofrecen una hidratación y protección suave. Despídete de las irritaciones y saluda a una piel radiante y saludable.\"}]", "gen_ai.response.model": "jina-reranker-v2-base-multilingual", "gen_ai.usage.input_tokens": 896, "gen_ai.usage.total_tokens": 896, "orq.billing.billable": true, "orq.billing.input_cost": 0.00001613, "orq.billing.pricing_tier": "standard", "orq.billing.total_cost": 0.00001613, "orq.model.id": "4666d24e-ae9c-11ef-9414-325096b39f47", "orq.model.is_private": false, "orq.model.provider": "jina", "orq.model.type": "rerank", "orq.organization_id": "55c3d968-8390-4e46-af01-e46857f37ced", "orq.product": "router", "orq.span_type": "span.rerank", "orq.workspace_id": "3de3a12f-6c52-46b5-a195-539bc40e99c9", "service.instance.id": "01KR9HSA5JCBQRN8ZFN9KJZ23G", "service.name": "responses-api", "service.version": "0.1.0", "telemetry.sdk.language": "go", "telemetry.sdk.name": "opentelemetry", "telemetry.sdk.version": "1.43.0" } }}
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
Header
Description
X-Orq-Signature
HMAC-SHA256 hex digest of the request body
X-Orq-Hook-ID
The event ID
X-Orq-Event
The event type
Idempotency-Key
Stable for the same event and endpoint, so retries and replays carry the same value
User-Agent
Orq-Webhook/2.0
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.