Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orq.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 Organization and select Webhooks. Click Create and configure the following:
  • Name: a unique name to identify this webhook
  • URL: the endpoint on your server that will receive the HTTP POST requests
  • Event types: choose which events should trigger this webhook
Webhook creation form with name, URL, and event type fields
When deployment events are selected, an additional option appears:
  • Send me everything to receive events from all deployments
  • Let me select individual deployments to scope the webhook to specific ones.
After clicking Create, a Save your signing secret dialog appears with your secret. Copy and store it securely, as it will not be shown again. If you lose it, you will need to create a new webhook.
Use the signing secret to verify incoming requests.

​
Event Types

Orq.ai sends webhooks for the following events, grouped by resource:
GroupEvent
Agentagent.created
agent.updated
agent.deleted
Deploymentdeployment.created
deployment.updated
deployment.deleted
deployment.invoked
Promptprompt.created
prompt.updated
prompt.deleted
LLMllm.chat_completion
llm.response
llm.embedding
llm.rerank

​
Delivery Metrics

Webhooks dashboard showing delivery metrics, event deliveries chart, response time chart, 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 below with its URL, configured event types, and signing secret.

​
Payload Structure

All CRUD events share the same envelope. request_id is an optional string that identifies the originating API request. It is present when the event was triggered by a traceable API call, and absent for system-initiated events.

​
Agent

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "agent.created",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<agent_id>",
      "key": "<agent_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "agent.updated",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<agent_id>",
      "key": "<agent_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "agent.deleted",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<agent_id>",
      "key": "<agent_name>",
      "version": "<version>"
    }
  }
}

​
Deployment

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "deployment.created",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<deployment_id>",
      "key": "<deployment_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "deployment.updated",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<deployment_id>",
      "key": "<deployment_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "deployment.deleted",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<deployment_id>",
      "key": "<deployment_name>",
      "version": "<version>"
    }
  }
}
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.
{
  "id": "wk_log_01kkypj82sqrzg1s9t9v9p13jv",
  "created": "2026-03-17T20:07:31.161517094Z",
  "type": "deployment.invoked",
  "metadata": {
    "deployment_id": "<deployment_id>",
    "deployment_key": "<deployment_name>",
    "deployment_variant_id": "<variant_id>",
    "deployment_variant_version": "<variant_version>",
    "deployment_log_id": "<log_id>",
    "deployment_url": "<deployment_url>",
    "deployment_variant_url": "<variant_url>",
    "deployment_log_url": "<log_url>"
  },
  "data": {
    "contact_id": "<identity_ulid>",
    "prompt_config": {
      "messages": [
        { "role": "system", "content": "<system_message>" },
        { "role": "user", "content": "<user_message>", "id": "<message_id>" }
      ],
      "model": "gpt-4o-mini",
      "model_db_id": "<model_db_id>",
      "model_parameters": {
        "temperature": 0.2,
        "maxTokens": 1000,
        "topK": 5,
        "topP": 0,
        "frequencyPenalty": 0,
        "presencePenalty": 0
      },
      "model_type": "chat",
      "provider": "openai",
      "stream": false
    },
    "choices": [
      {
        "finish_reason": "stop",
        "index": 0,
        "message": { "role": "assistant", "content": "<response>" }
      }
    ],
    "variables": [
      { "is_pii": false, "key": "<variable_key>", "value": "<variable_value>" }
    ],
    "performance": {
      "first_time_to_token": 0,
      "latency": 1125.2,
      "tokens_per_second": 8.89
    },
    "usage": {
      "completion_tokens": 10,
      "completion_tokens_details": { "reasoning_tokens": 0 },
      "prompt_tokens": 122,
      "prompt_tokens_details": { "cached_tokens": 0 },
      "total_tokens": 132
    },
    "billing": {
      "billable": true,
      "input_cost": 0.0000183,
      "output_cost": 0.000006,
      "total_cost": 0.0000243
    },
    "tools": [],
    "metadata": {},
    "thread": {
      "id": "<thread_id>",
      "tags": ["<tag1>", "<tag2>"]
    },
    "status": 200
  }
}
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

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "prompt.created",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<prompt_id>",
      "key": "<prompt_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "prompt.updated",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<prompt_id>",
      "key": "<prompt_name>",
      "version": "<version>"
    }
  }
}

{
  "id": "evt_<ulid>",
  "object": "event",
  "type": "prompt.deleted",
  "created": 1742123456,
  "api_version": "1.0",
  "workspace": "<workspace_id>",
  "project": "<project_id>",
  "correlation_id": "<correlation_id>",
  "data": {
    "object": {
      "id": "<prompt_id>",
      "key": "<prompt_name>",
      "version": "<version>"
    }
  }
}

​
LLM

LLM events fire after the gateway processes a chat completion, response, embedding, or rerank call. The data block carries the OpenTelemetry GenAI semantic-convention span attributes so subscribers receive the full request and response payload inline. 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).
  • The envelope’s top-level project field is omitted when the span has no associated project.
{
  "id": "evt_a5a771765f4959ddf615093e39",
  "object": "event",
  "type": "llm.chat_completion",
  "created": 1778437602,
  "api_version": "1.0",
  "workspace": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
  "correlation_id": "e98f5b18ddb209743950528b1f3a41a0",
  "data": {
    "span_id": "f3313eaecc8b24bc",
    "trace_id": "e98f5b18ddb209743950528b1f3a41a0",
    "parent_span_id": "f99eb9200abf32e6",
    "span_type": "span.chat_completion",
    "name": "chat gpt-4o-mini",
    "start_time": "2026-05-10T18:26:41.325945Z",
    "end_time": "2026-05-10T18:26:41.327398792Z",
    "duration_ns": 1453792,
    "status": "OK",
    "attributes": {
      "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"_id\":\"text_01kr9j8e1dm0t92b2y2fxttc8w\",\"kind\":\"text\",\"text\":\"Hello\"}]}]",
      "gen_ai.operation.name": "chat",
      "gen_ai.output.messages": "[{\"role\":\"agent\",\"parts\":[{\"_id\":\"text_01kr9j8e1ft8xm3sstfh2wzbsm\",\"kind\":\"text\",\"text\":\"Hello! How can I assist you today?\"}]}]",
      "gen_ai.provider.name": "openai",
      "gen_ai.request.model": "gpt-4o-mini",
      "gen_ai.response.finish_reasons": ["stop"],
      "gen_ai.response.model": "gpt-4o-mini",
      "gen_ai.system_instructions": "{\"role\":\"user\",\"parts\":[{\"_id\":\"text_01kr9j8e1dm0t92b2y2fxttc8w\",\"kind\":\"text\",\"text\":\"Hello\"}]}",
      "gen_ai.usage.input_tokens": 8,
      "gen_ai.usage.output_tokens": 9,
      "gen_ai.usage.total_tokens": 17,
      "orq.billing.billable": false,
      "orq.billing.cache_read_cost": 0,
      "orq.billing.cache_write_cost": 0,
      "orq.billing.input_cost": 0.0000012,
      "orq.billing.integration_id": "01KQ9Y9MS8ZHV99ZG60Q32C36E",
      "orq.billing.output_cost": 0.0000054,
      "orq.billing.pricing_tier": "standard",
      "orq.billing.total_cost": 0.0000066,
      "orq.model.id": "85b18e5b-76a0-48dc-99b5-5738c35c9c85",
      "orq.model.is_private": false,
      "orq.model.provider": "openai",
      "orq.model.type": "chat",
      "orq.organization_id": "3d4c4097-3ad7-48f8-965e-71d8d25ddb1b",
      "orq.product": "router",
      "orq.span_type": "span.chat_completion",
      "orq.workspace_id": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
      "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"
    }
  }
}

{
  "id": "evt_23c9e52b6b1a38d64b9d034791",
  "object": "event",
  "type": "llm.response",
  "created": 1778437600,
  "api_version": "1.0",
  "workspace": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
  "project": "<project_ulid>",
  "correlation_id": "b12335e85a37ed3ce191a5268fa87111",
  "data": {
    "span_id": "6b2508f591d1b112",
    "trace_id": "b12335e85a37ed3ce191a5268fa87111",
    "parent_span_id": "f7fdfb8e41c2d9e1",
    "span_type": "span.responses",
    "name": "chat gpt-4o-mini",
    "start_time": "2026-05-10T18:26:39.414839Z",
    "end_time": "2026-05-10T18:26:39.422535042Z",
    "duration_ns": 7696042,
    "status": "OK",
    "attributes": {
      "gen_ai.operation.name": "responses",
      "gen_ai.provider.name": "openai",
      "gen_ai.request.model": "gpt-4o-mini",
      "gen_ai.response.finish_reasons": ["stop"],
      "gen_ai.response.id": "resp_0608254bd32f043b016a00b1642dfc81a4a1f3c41bec5cf70a",
      "gen_ai.response.model": "gpt-4o-mini-2024-07-18",
      "gen_ai.usage.input_tokens": 15,
      "gen_ai.usage.output_tokens": 15,
      "gen_ai.usage.total_tokens": 30,
      "openresponses.background": false,
      "openresponses.completed_at": "1778430310",
      "openresponses.created_at": 1778430308,
      "openresponses.frequency_penalty": 0,
      "openresponses.input": "[{\"content\":[{\"type\":\"input_text\",\"text\":\"Count from 1 to 5.\"}],\"id\":\"msg_01kr9j8c5p9v4y4xyhdqhg117n\",\"role\":\"user\",\"status\":\"completed\",\"type\":\"message\"}]",
      "openresponses.input.items.count": 1,
      "openresponses.object": "response",
      "openresponses.output": "[{\"content\":[{\"type\":\"output_text\",\"text\":\"1, 2, 3, 4, 5.\",\"annotations\":[],\"logprobs\":[]}],\"id\":\"msg_0608254bd32f043b016a00b1668cb881a480fe34962427a227\",\"role\":\"assistant\",\"status\":\"completed\",\"type\":\"message\"}]",
      "openresponses.output.items.count": 1,
      "openresponses.parallel_tool_calls": true,
      "openresponses.presence_penalty": 0,
      "openresponses.service_tier": "default",
      "openresponses.status": "completed",
      "openresponses.store": true,
      "openresponses.stream": false,
      "openresponses.temperature": 1,
      "openresponses.text": "{\"format\":{\"type\":\"text\"},\"verbosity\":\"medium\"}",
      "openresponses.tool_choice": "\"auto\"",
      "openresponses.tools.count": 0,
      "openresponses.top_logprobs": 0,
      "openresponses.top_p": 1,
      "openresponses.truncation": "auto",
      "orq.billing.billable": false,
      "orq.billing.cache_read_cost": 0,
      "orq.billing.cache_write_cost": 0,
      "orq.billing.input_cost": 0.00000225,
      "orq.billing.integration_id": "01KQ9Y9MS8ZHV99ZG60Q32C36E",
      "orq.billing.output_cost": 0.000009,
      "orq.billing.pricing_tier": "standard",
      "orq.billing.total_cost": 0.00001125,
      "orq.model.id": "85b18e5b-76a0-48dc-99b5-5738c35c9c85",
      "orq.model.is_private": false,
      "orq.model.provider": "openai",
      "orq.model.type": "chat",
      "orq.organization_id": "3d4c4097-3ad7-48f8-965e-71d8d25ddb1b",
      "orq.product": "router",
      "orq.span_type": "span.responses",
      "orq.workspace_id": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
      "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"
    }
  }
}

{
  "id": "evt_48eeb9fad80359ed8a52342235",
  "object": "event",
  "type": "llm.embedding",
  "created": 1778437604,
  "api_version": "1.0",
  "workspace": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
  "correlation_id": "8d8bad94ac9a97d14fe783daf34cb3e5",
  "data": {
    "span_id": "ac6e9de774652b62",
    "trace_id": "8d8bad94ac9a97d14fe783daf34cb3e5",
    "parent_span_id": "8ac42a0d3556cd44",
    "span_type": "span.embedding",
    "name": "embeddings text-embedding-3-small",
    "start_time": "2026-05-10T18:26:43.638991Z",
    "end_time": "2026-05-10T18:26:43.6414215Z",
    "duration_ns": 2430500,
    "status": "OK",
    "attributes": {
      "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Hello\"}]}]",
      "gen_ai.operation.name": "embeddings",
      "gen_ai.output.count": 1,
      "gen_ai.output.dimensions": 1536,
      "gen_ai.output.object": "list",
      "gen_ai.provider.name": "openai",
      "gen_ai.request.model": "text-embedding-3-small",
      "gen_ai.response.model": "text-embedding-3-small",
      "gen_ai.usage.input_tokens": 1,
      "gen_ai.usage.total_tokens": 1,
      "http.response.status_code": 200,
      "orq.billing.billable": false,
      "orq.billing.input_cost": 2e-8,
      "orq.billing.integration_id": "01KQ9Y9MS8ZHV99ZG60Q32C36E",
      "orq.billing.pricing_tier": "standard",
      "orq.billing.total_cost": 2e-8,
      "orq.model.id": "679a4486-1936-4287-bcdd-f6dc0df8389c",
      "orq.model.is_private": false,
      "orq.model.provider": "openai",
      "orq.model.type": "embedding",
      "orq.organization_id": "3d4c4097-3ad7-48f8-965e-71d8d25ddb1b",
      "orq.product": "router",
      "orq.span_type": "span.embedding",
      "orq.workspace_id": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
      "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"
    }
  }
}

{
  "id": "evt_194c87ee3cee419a20ccd730a7",
  "object": "event",
  "type": "llm.rerank",
  "created": 1778437606,
  "api_version": "1.0",
  "workspace": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
  "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": "3d4c4097-3ad7-48f8-965e-71d8d25ddb1b",
      "orq.product": "router",
      "orq.span_type": "span.rerank",
      "orq.workspace_id": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
      "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"
    }
  }
}

​
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

HeaderDescription
X-Orq-SignatureHMAC-SHA256 hex digest of the signature payload
X-Orq-Hook-IDThe event ID
X-Orq-EventThe event type
User-AgentOrq-Webhook/2.0

​
How the signature is computed

The signature is computed over a JSON string containing exactly these three fields in this order. The type of created differs by event: an integer (Unix timestamp) for CRUD events, and an ISO-8601 string for deployment.invoked. The value must be preserved as-is from the original payload without type conversion. CRUD events: 
{
  "id": "evt_01kkyjd5d7drqxnmyzfxpracz3",
  "created": 1773773690,
  "type": "agent.updated"
}
deployment.invoked: 
{
  "id": "wk_log_01kkyhyxwc6413gh8xfbqydge2",
  "created": "2026-03-17T18:47:03.820244586Z",
  "type": "deployment.invoked"
}
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

import express, { Request, Response } from "express";
import crypto from "crypto";

const app = express();
const webhookSecret = "orq_wk_...";

function verifySignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  // timingSafeEqual throws if buffers differ in length; check first
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks", express.json(), (req: Request, res: Response) => {
  const signature = req.headers["x-orq-signature"] as string;
  const { id, created, type } = req.body;
  const signaturePayload = JSON.stringify({ id, created, type });

  if (!verifySignature(signaturePayload, signature, webhookSecret)) {
    return res.status(400).send("Invalid signature");
  }

  res.json({ received: true });
});

app.listen(3000);