Webhooks & Integration

• Webhook Setup & Configuration

  Register HTTPS callback endpoints through the OpenRouter dashboard, select which event types to receive, and generate signing secrets for payload verification — all in under five minutes.

  Start webhook setup →

• Event Types & Payloads

  Subscribe to usage alerts, credit thresholds, key lifecycle changes, and provider status events. Each event type delivers a structured JSON payload with exactly the fields your system needs.

  Browse event types →

• Delivery & Retry Logic

  Failed deliveries retry with exponential backoff across a 72-hour window. Understand the retry schedule, how to handle idempotency, and when to investigate undelivered events.

  Understand retry behavior →

• Security & Signature Verification

  Verify every incoming webhook with HMAC-SHA256 signature validation using your unique signing secret. Prevent spoofed payloads and man-in-the-middle tampering.

  Implement signature verification →

Setting Up OpenRouter Webhooks

Webhook configuration lives in the Integrations section of your OpenRouter dashboard. Click Add Endpoint and provide an HTTPS URL where OpenRouter will POST event payloads. The URL must use TLS — the platform rejects HTTP endpoints outright to prevent sensitive payload data from traversing the network in plaintext. Each endpoint can subscribe to a subset of available event types, so you can route usage alerts to your monitoring system, credit notifications to your finance team's Slack channel, and key expiration events to your security automation without creating separate webhook registrations for each destination.

During endpoint creation, OpenRouter generates a unique signing secret — a long random string displayed once and never shown again. Store this secret in your application's secrets manager immediately. The platform uses it to create an HMAC-SHA256 signature of every webhook payload, which your endpoint validates on receipt. Without the secret, you cannot distinguish genuine OpenRouter webhooks from forged requests, so treat its security with the same care you apply to API keys.

After saving the endpoint configuration, OpenRouter sends a test event with type webhook.test to verify connectivity. Your endpoint should respond with HTTP 200 within 10 seconds. If the test succeeds, the webhook becomes active and begins delivering live events. A failed test shows the HTTP status code and response body in the dashboard for debugging — common failure causes include TLS certificate issues, firewall rules blocking OpenRouter IP ranges, or endpoint timeouts on slow application boot sequences.

Event Type Reference

Each webhook event carries a structured JSON payload in the POST body. The top-level structure is consistent across all event types: an id field uniquely identifies the event for idempotency, type matches the event subscription category, created_at provides an ISO 8601 timestamp, and data contains the event-specific payload fields documented in the table above. Your endpoint should use the id field to deduplicate events — OpenRouter guarantees at-least-once delivery, meaning your endpoint may receive the same event more than once during retry cycles. Processing an event whose ID you have already handled should be a no-op.

Usage threshold events fire when your token consumption crosses a percentage of your account limit. Configure the percentage in the dashboard — 80% is the recommended starting point, giving your team time to investigate before the hard limit triggers 429 responses. Credit balance events alert you when your prepaid credits drop below a configurable dollar amount, helping teams avoid service interruptions from depleted balances. Key lifecycle events support security automation workflows: a key.expiring event can trigger an automated rotation script, while key.revoked confirms that a manual or automated revocation completed successfully.

Model status change events provide real-time awareness of provider outages. When a model becomes unavailable due to upstream provider issues, the webhook delivers the model ID and affected provider. Your application can use this information to trigger fallback routing or notify operations teams without polling the provider status endpoint. Follow the NIST AI standards program for guidance on designing resilient systems that respond to infrastructure events with appropriate containment and recovery procedures.

Payload Size and Rate Considerations

Webhook payloads are compact — typically under 1KB of JSON — and the platform batches events that occur within the same second into a single delivery when multiple events share the same endpoint subscription. This batching reduces the number of HTTP calls your endpoint must handle during bursts of activity, such as when a team creates multiple API keys during an onboarding session or when several models simultaneously report status changes during a widespread provider incident.

Delivery Retry Logic and Failure Handling

OpenRouter considers a webhook delivery successful when your endpoint responds with an HTTP 2xx status code within 10 seconds. Any other response — a 4xx client error, a 5xx server error, a network timeout, or a connection refusal — triggers the retry schedule. The platform retries at increasing intervals: 5 minutes after the first failure, then 15 minutes, 1 hour, 6 hours, 24 hours, and finally 48 hours. After the final attempt at approximately 72 hours from the original event, the delivery is marked as permanently failed and no further retries occur.

Permanently failed deliveries remain visible in your webhook dashboard with the complete event payload and a log of every retry attempt including timestamps, response codes, and error messages. This audit trail lets your team investigate persistent failures — misconfigured TLS certificates, changed endpoint URLs, or application bugs that reject valid payloads — and reprocess the event manually once the issue is resolved. For organizations that require even longer retention or custom retry policies, the Better Business Bureau's accredited technology resources include guidance on evaluating webhook reliability guarantees from service providers before integrating them into critical business workflows.

Idempotency and Duplicate Event Handling

Because retries can deliver the same event multiple times, every webhook handler must be idempotent. Use the event id field as a deduplication key — store processed event IDs in a database or cache with a TTL that exceeds the 72-hour retry window, and skip processing for any event ID you have already handled successfully. This pattern protects against double-processing side effects like sending duplicate Slack notifications, running the same key rotation script twice, or recording inflated usage statistics from repeated threshold events.

Webhook Security and Signature Verification

Every webhook delivery from OpenRouter includes an X-OpenRouter-Signature HTTP header. This header contains an HMAC-SHA256 hash of the raw request body, computed using your webhook's unique signing secret as the HMAC key. To verify that a webhook genuinely originated from OpenRouter and was not modified in transit, your endpoint must compute the same hash and compare it to the header value in constant time. A mismatch indicates either a spoofed request or payload tampering — in either case, the request should be rejected with HTTP 401.

Signature verification code is concise: hash the raw request body bytes with HMAC-SHA256 using your signing secret, encode the result as a hexadecimal string, and compare it to the header value. Do not parse or transform the request body before hashing — even whitespace changes between the bytes OpenRouter sent and the bytes your application receives will produce a mismatched signature, so read the raw body from the HTTP framework's request stream before any middleware deserializes it into a JSON object.

Beyond signature verification, configure your firewall to accept inbound traffic on the webhook endpoint port only from OpenRouter's published IP ranges. This defense-in-depth approach means even if an attacker discovered your endpoint URL, their requests would be blocked at the network layer before reaching your application. Combine IP allowlisting with signature verification for the strongest security posture, and rotate your signing secret during regular security review cycles just as you would rotate API keys or database credentials.

Frequently Asked Questions About Webhooks