OpenAI Webhook Signature Verification Starts with Raw Bytes
OpenAI webhook signature verification must run against the original HTTP body and required webhook headers before JSON parsing or business processing. This guide defines the raw-body boundary, official SDK verification path, replay and duplicate controls, secret rotation, fast acknowledgments, and acceptance fixtures for a receiver that triggers production actions safely.

An OpenAI callback arrives as an HTTP POST with a JSON body. The request carries an event identifier and timestamp in headers named webhook-id and webhook-timestamp. A third header, webhook-signature, carries the signature. Verification uses the original request body. A framework that parses JSON first can change spacing or serialization and destroy the exact byte sequence the sender signed.
I treat the raw-body handler as a security boundary: capture bounded bytes, pass those bytes and headers to the official verifier, accept the verified event, and only then enqueue business work.
TL;DR
- Preserve the original HTTP body and required webhook headers, then run the official SDK unwrap helper before parsing or acting.
- Reject missing or invalid verification input with a closed response and zero business side effects. Malformed and stale input is invalid.
- Use webhook-id as the deduplication key because OpenAI retries failed deliveries and can send duplicate events.
- Acknowledge verified events quickly, move work to a durable queue, and test secret rotation plus replay and crash paths.
Verification belongs before JSON parsing
OpenAI's webhooks guide shows a project callback with webhook-id and webhook-timestamp metadata. The signature arrives under webhook-signature. OpenAI directs receivers to verify it with the signing secret issued when the endpoint is created. The official SDK unwrap() helper verifies and parses the event, raising an error for invalid input.
The guide's server examples preserve the raw text or byte body. Express uses a text parser for application/json rather than its JSON parser. Python passes the bytes exposed as request.data. The Go example says to verify the original bytes before any JSON parsing.
Middleware ordering determines which bytes reach the verifier. Body parsers and JSON reserialization can change the signed content. Character-set conversion and newline normalization can do the same. Route the webhook endpoint through a dedicated raw-body path with an explicit size limit. Preserve the original headers in the framework representation expected by the SDK.
After verification succeeds, validate the event type and schema your application supports. Signature validity authenticates the delivered message under the configured secret. Business authorization still belongs to the receiving application. A completed-response event can update only the tenant and the workflow resource that the receiver has already associated with that OpenAI project.
The LLM request signing guide explains the broader message-integrity pattern. OpenAI webhooks use the Standard Webhooks contract documented by OpenAI, so the official helper is the preferred implementation path.
The signing secret is endpoint security material
OpenAI displays a signing secret when the project endpoint is created and instructs the receiver to keep it server-side. Store it in the deployment's secret manager and inject it into the webhook process. Give production its own endpoint and secret. Do the same for staging. A developer endpoint should trust only its assigned secret.
Treat secret access as a narrow runtime permission. Application logs, exception trackers, deployment output, and test fixtures should contain redacted labels rather than the value. Record a secret version or key reference in verification telemetry so an operator can identify which configured generation accepted an event.
OpenAI's guide provides a dashboard control for rotating a misplaced or exposed signing secret. Plan rotation before an incident. The Standard Webhooks specification allows multiple signatures in the signature header to support overlap during rotation and requires timestamp checks plus constant-time comparison for symmetric signatures. Official SDKs should carry those cryptographic details.
My blunt view is that handwritten HMAC code in a webhook controller is an unnecessary security review tax. Use the official helper and keep the dependency pinned and updated. Spend review time on middleware order, replay state, tenant binding, and side effects.
Timestamp and webhook-id address different risks
The Standard Webhooks scheme signs the message ID and payload together. It also signs the attempt timestamp. Its specification describes the timestamp as an anti-replay input and the message ID as a stable identifier retained across retries. OpenAI's guide tells receivers to use webhook-id as an idempotency key.
Apply the SDK's timestamp verification policy and keep system clocks synchronized. A stale signed request should end before queue insertion. Record the bounded timestamp, verification outcome, endpoint ID, and secret version. The event payload can contain sensitive provider data, so telemetry should favor identifiers and fingerprints over full bodies.
Deduplication needs durable state. Insert webhook-id under a unique constraint before acknowledging work. Associate it with the event type, payload fingerprint, receive time, processing state, and target workflow. A second delivery with the same ID and same fingerprint can return the established acknowledgment. A matching ID carrying a different fingerprint belongs in a security hold.
The AI audit log schema provides a useful structure for correlation and outcome fields. Keep signature-verification evidence distinct from the later business-action record, then join them by webhook ID and queue message ID.
Fast acknowledgment needs a durable handoff
OpenAI asks webhook endpoints to return a successful 2xx response quickly and recommends background processing for non-trivial work. Failed or slow deliveries are retried with exponential backoff for up to 72 hours. Redirect responses are treated as failures. OpenAI also warns that duplicate event copies can occur.
A safe receiver performs a short synchronous sequence. It enforces method and size limits before capturing raw bytes. It then verifies the signature and timestamp, validates the supported event envelope, reserves the deduplication key, writes a durable queue item, and returns 2xx. Model retrieval, database changes, notifications, and tool calls happen in the worker.
The acknowledgment should follow the durable queue commit. Returning 2xx before that commit can lose the event when the process crashes. Returning an error after a successful commit invites another delivery, which is safe only when the unique webhook ID returns the existing queue item.
Place a small metal click counter beside the test terminal. Send the same signed event five times. The HTTP access log may show five accepted deliveries, while the counter for business effects should move once. That physical split makes delivery semantics obvious.
The AI agent observability guide covers runtime traces. Webhook acceptance adds a durable receipt and deduplication state before the longer worker trace begins.
Failure responses should stay narrow
Use 405 for an unsupported method and 413 for a body beyond the configured limit. Use a closed client error for missing or invalid signature input. Keep public response bodies generic. Detailed reasons belong in protected telemetry because header parsing and timestamp detail can help an attacker tune requests.
Verification failure must produce zero queue entries, database writes, provider retrieval calls, or downstream tool effects. Schema failure after successful verification also stops before business processing. Track those as separate stages so an operator can distinguish an unauthenticated request from an authenticated event type that lacks a handler in the current deployment.
Rate limits belong at the public endpoint, with enough capacity for legitimate retry bursts. Network controls and a web application firewall can reduce noise, while signature verification remains the authenticity decision. TLS protects transport to your endpoint. The signed message binds the body and webhook metadata under the secret.
The AI audit log chain-of-custody guide applies when verification records become incident evidence. Preserve configuration version, receive timestamp, body fingerprint, header fingerprints, outcome, and queue commit ID under approved retention.
Acceptance tests need byte changes and process crashes
Build signed fixtures with the official OpenAI or Standard Webhooks test tooling used by your stack. Exercise the complete deployed HTTP route rather than calling the verifier function alone. Include these cases:
- A valid request using the exact raw body bytes.
- The same JSON parsed and reserialized with changed whitespace, producing rejection.
- Missing
webhook-id, timestamp, or signature headers. - A timestamp outside the accepted tolerance and a synchronized valid timestamp.
- An invalid signature with a plausible event body.
- Five deliveries sharing one webhook ID and payload fingerprint.
- One repeated webhook ID paired with a changed payload fingerprint.
- A valid unsupported event type.
- A queue commit followed by process termination before the HTTP response.
Also test a 2xx response delayed beyond the receiver's operating target. Test rotation overlap, then retirement of the previous secret generation.
Inspect the queue and business-effect stores after every negative fixture. Their row count should stay unchanged. For crash recovery, the provider retry should find the existing deduplication record and return the established outcome.
DeepInspect
DeepInspect applies to authenticated user or agent HTTP traffic deliberately routed through its proxy to an LLM endpoint. It can enforce identity-aware policy and preserve a decision record for those model requests. That boundary can cover the original routed request that later causes OpenAI to emit an event.
The public webhook receiver remains owned by the application. It owns raw-body capture, signing-secret custody, signature and timestamp verification, deduplication, event schema validation, queue durability, tenant binding, and every downstream side effect. OpenAI owns delivery and its signing implementation. DeepInspect should never be described as the verifier for a callback sent directly to the application's webhook URL.
Join the routed model-request decision to the verified webhook receipt using approved provider and application correlation identifiers. The two records then show request authorization and callback authenticity under their proper owners.
Book a demo today.