Webhook

Step 1: Set up your webhook endpoint

1. Accept application/json content type
2. Return a 2xx status code on success
3. Be publicly accessible from the internet

Step 2: Enable Broadcast in OpenRouter

Step 3: Configure Webhook

• URL: Your webhook endpoint URL (e.g., https://api.example.com/traces)
• Method (optional): HTTP method to use, either POST (default) or PUT
• Headers (optional): Custom HTTP headers as a JSON object for authentication or other purposes

{
  "Authorization": "Bearer your-token",
  "X-Webhook-Signature": "your-webhook-secret"
}

Step 4: Test and save

Step 5: Send a test trace

mTLS client certificate

• Client certificate: the certificate OpenRouter presents, optionally followed by its intermediate certificates.
• Private key: the certificate’s private key, unencrypted, in PKCS#8 (BEGIN PRIVATE KEY), PKCS#1 RSA (BEGIN RSA PRIVATE KEY) or SEC1 EC (BEGIN EC PRIVATE KEY) format.
• Server CA certificates (optional): CA certificates to trust for your endpoint’s server certificate, for example when it is signed by a private CA. They are added to the public root certificates, not used instead of them.

openssl pkey -in client-key.pem -out client-key-decrypted.pem

How mTLS changes delivery

• The endpoint URL must use https://.
• Redirects to a different origin are not followed while a client certificate is set.
• Traces to this destination are sent from OpenRouter’s queue workers in each data region (Global, US and EU) instead of inline, with a single delivery attempt.
• Queued messages are limited to 5 MB, so a very large trace payload can be truncated or dropped.
• Test Connection and Send Trace cannot present the certificate from the dashboard. Instead of contacting your endpoint, they check that the certificate and key are valid PEM, belong together and have not expired. The TLS handshake with your endpoint is first tested by a real delivery, so make a request through OpenRouter and confirm that your endpoint receives the trace.
• Replace the certificate before it expires: deliveries fail once it has expired.
• If mTLS access is removed from your organization, the saved certificate stays in place but the destination cannot be turned on or kept on. Remove the certificate or turn the destination off before saving other changes to it.

Payload format

• Trace and span IDs
• Timestamps and duration
• Model and provider information
• Token usage and cost
• Request and response content (with multimodal content stripped)

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "openrouter" } }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "abc123...",
              "spanId": "def456...",
              "name": "chat",
              "startTimeUnixNano": "1705312800000000000",
              "endTimeUnixNano": "1705312801000000000",
              "attributes": [
                { "key": "gen_ai.request.model", "value": { "stringValue": "openai/gpt-4" } },
                { "key": "gen_ai.usage.prompt_tokens", "value": { "intValue": "100" } },
                { "key": "gen_ai.usage.completion_tokens", "value": { "intValue": "50" } }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Use cases

• Custom analytics pipelines: Send traces to your own data warehouse or analytics system
• Internal monitoring tools: Integrate with proprietary observability platforms
• Event-driven architectures: Trigger workflows based on LLM usage
• Compliance logging: Store traces in systems that meet specific regulatory requirements
• Development and testing: Use services like webhook.site to inspect trace payloads

Custom Metadata

Supported Metadata Keys

Example

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Process this order..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "order_processing_001",
    "trace_name": "Order Processing Pipeline",
    "generation_name": "Extract Order Details",
    "order_id": "ORD-12345",
    "priority": "high"
  }
}

Accessing Metadata in Your Webhook

{
  "resourceSpans": [{
    "scopeSpans": [{
      "spans": [{
        "attributes": [
          { "key": "trace.metadata.order_id", "value": { "stringValue": "ORD-12345" } },
          { "key": "trace.metadata.priority", "value": { "stringValue": "high" } }
        ]
      }]
    }]
  }]
}

Additional Context

• The user field maps to user.id in span attributes
• The session_id field maps to session.id in span attributes
• All standard GenAI semantic conventions (gen_ai.*) are included for model, token, and cost data

Privacy Mode