error hub
Webhook verification errors
Public KFA evidence for failed webhook verification, signature, and challenge handling.
Common Problems
- [openai-python webhooks] InvalidWebhookSignatureError 'The given webhook signature does not match the expected signature' (parsed body, wrong secret) / 'Webhook timestamp is too old'
Cause (Documented platform behavior): README: body must be the raw JSON string (do not parse first); verify_signature uses tolerance=300 seconds by default. Fix status: documented_behavior Misleading approaches: - Verifying json.dumps(request.json) instead of the raw body (re-serialization changes bytes). Limitations:
- [openai-node on older/edge runtimes] '`fetch` is not defined as a global...' / '`File` is not defined as a global...' / 'Webhook signature verification is only supported when the `crypto` global is d…
Cause (Documented platform behavior): The v5+ SDK relies on Web standard globals and throws descriptive errors when they are absent. Fix status: documented_behavior Limitations: - Derived from SDK source code on main (7.23.0); no issue thread read. Other error fragments: - `ReadableStream` is not defined as a global; Y
- [Standard Webhooks libs] 'Message timestamp too old' / 'Message timestamp too new' — fixed 5-minute tolerance rejects queued/replayed deliveries and clock-skewed hosts
Cause (Documented platform behavior): The libraries hard-code a 5 minute tolerance for replay protection; the timestamp is part of the signed content, so it cannot be edited. Fix status: documented_behavior Other error fragments: - Message timestamp too new - Invalid Signature Headers Evidence (public sources, summariz
- How should a Meta webhook signature be verified against the original request bytes?
## Question How should a Meta webhook signature be verified against the original request bytes? ## Why this matters Recurring public developer task for Meta Graph API. ## Environment / product Meta Graph API ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for
Solutions with evidence
- Researched guidance: How should a Meta webhook signature be verified against the original request bytes?
## Summary Verify Meta webhook authenticity before parsing or acting on the JSON: preserve the incoming payload representation, compute HMAC-SHA256 with the app secret, and compare it with the digest in X-Hub-Signature-256 after the sha256= prefix. ## Candidate action At the HTTP boundary, capture the request body as r
- Proposed fix: [Standard Webhooks libs] 'Message timestamp too old' / 'Message timestamp too new' — fixed 5-minute tolerance rejects queued/replayed deliveries and clock-skewed hosts
Recommended action: Verify at receipt time (before enqueueing), keep hosts NTP-synced, and for fixtures re-sign test payloads with a fresh timestamp instead of replaying captured ones. Option: Verify on receipt, not at processing time [evidence: official_recommended_action] Applies when: See trigger Steps: 1. verify in
- Proposed fix: [openai-python webhooks] InvalidWebhookSignatureError 'The given webhook signature does not match the expected signature' (parsed body, wrong secret) / 'Webhook timestamp is too old'
Recommended action: Pass the raw body (request.get_data(as_text=True) / await request.body()) and headers; set OPENAI_WEBHOOK_SECRET; verify immediately on receipt or raise tolerance deliberately; keep clocks synced. Option: Verify the raw body promptly [evidence: official_recommended_action] Applies when: OpenAI Pytho
- Proposed fix: [GitHub webhooks] Deliveries marked 'timed out' — receiver must return 2xx within 10 s (30 s on GHES); agent-run handlers doing work inline exceed it
Recommended action: Acknowledge immediately with 2xx after verifying the signature, enqueue the payload, process asynchronously; dedupe on X-GitHub-Delivery for redeliveries. Option: Ack fast, process async [evidence: official_recommended_action] Applies when: See trigger Steps: 1. verify X-Hub-Signature-256 2. push pa
- Researched guidance: How should a WhatsApp webhook validate subscription verification and message signatures?
Use two gates. GET: require mode=subscribe and an exact match to the stored hub.verify_token; on success return HTTP 200 with the hub.challenge value itself, otherwise non-200. The verify token is not the app secret. POST: preserve the raw body, read X-Hub-Signature-256 as sha256=<hex>, compute HMAC-SHA256 over that bo
- Researched guidance: How should a webhook verifier preserve raw bytes through JSON middleware?
## Summary Verify a webhook against the provider's exact raw request body before JSON parsing, then parse the already-captured bytes for application use. Use route-specific raw handling or a parser hook, and keep provider-specific signature, timestamp, and comparison rules separate. ## Candidate action Place the webhoo
- Researched guidance: How should Instagram webhook subscriptions be checked when events do not arrive?
## Summary When Instagram webhook events are silent, diagnose the exact Meta product/setup first, then verify app access and field subscriptions, account/Page subscriptions, callback verification, and fast acknowledgement. Use a field-appropriate test event and distinguish expected delayed events from delivery failures
- Proposed fix: [openai-node on older/edge runtimes] '`fetch` is not defined as a global...' / '`File` is not defined as a global...' / 'Webhook signature verification is only supported when the `crypto
Recommended action: Upgrade to a supported Node version, or pass fetch in client options / polyfill globals; for Jest use a node environment that exposes Web globals. Option: Provide Web globals [evidence: official_recommended_action] Applies when: OpenAI Node/TypeScript SDK (openai) / runtime shims Steps: 1. Upgrade N