WhatsApp Webhook Incident Runbook Template
When a WhatsApp webhook goes quiet, the person on call usually has no written procedure and checks things in a random order. This runbook template gives you an ordered triage list, a recovery sequence and a post-incident record. Fill in your service details and export it.
Fill in
WhatsApp Webhook Incident Runbook Template
Runbook: Order Status Notifier
Webhook endpoint: https://integrations.example.com/whatsapp/webhook On-call: Integration on-call Escalation: IT Operations Manager Queue: Inbound event queue Secrets location: Company secrets vault Status channel: #it-incidents
Severity 1 Definition
No inbound or status events processed for more than 15 minutes during business hours, or messages sent to the wrong recipient.
Triage Steps
| Step | Check | Result | Next action |
|---|---|---|---|
| 1 | Is the endpoint reachable over HTTPS with a valid certificate? | ||
| 2 | Does the verification GET with the verify token still succeed? | ||
| 3 | Are POST requests arriving? Check proxy and application logs | ||
| 4 | Does signature validation of the X-Hub-Signature-256 header pass with the current app secret? | ||
| 5 | Is the webhook subscription still active for the right fields? | ||
| 6 | Is the queue growing or are workers failing? | ||
| 7 | Has the access token expired or been revoked? |
Recovery Actions
1. Fix the root cause (certificate, secret, deployment, subscription). 2. Confirm new events arrive and are processed. 3. Replay failed events from the queue. Make processing idempotent by message ID so replays do not send duplicates. 4. Check whether the platform retried events during the outage and reconcile against your own records. 5. Post a status update to #it-incidents.
Communication Log
| Time | Audience | Message | Sent by |
|---|---|---|---|
Post-Incident Review
| Question | Answer |
|---|---|
| Start and end time | |
| Root cause | |
| Detection method and delay | |
| Follow-up actions and owners |
Sign-off
Platform behavior, retry windows and field names change. Verify details against the current Meta documentation for your API version before relying on this runbook.
Get a resilience review of your webhook design
Share your architecture and receive a short review of queueing, idempotency and monitoring gaps.
Optional. The tool and every export work without this. No spam.
How to use the runbook
Complete the fields once per integration, not per incident. Store the exported PDF where the on-call group can find it without logging into the system that is broken. During an incident, work down the triage table in order and write the result of each check. The order moves from cheap, common causes such as an expired certificate or rotated app secret toward rarer ones. Copy the communication log into your incident tool if you have one.
Why these checks, in this order
Webhook endpoints fail for a short list of reasons. The TLS certificate expired, the verify token or app secret changed during a deployment, a reverse proxy strips or alters the raw request body so signature validation fails, the subscription was removed, or workers crash and the queue backs up. Signature validation computes an HMAC SHA256 of the raw body with the app secret and compares it to the header, so any body rewriting breaks it. Check reachability and signatures before debugging business logic.
- Certificate and DNS
- Verify token and app secret
- Raw body preserved for signature check
- Subscription fields
- Queue depth and worker errors
Common mistakes
The most expensive mistake is replaying events without idempotency, which sends customers or staff the same notification twice. Key your processing on the message or status ID. Another mistake is returning slow responses: acknowledge the webhook quickly with a 200 and process asynchronously, otherwise the platform may treat the endpoint as failing and retry. Finally, teams forget to monitor the absence of events. Alert when no inbound or status events arrive for a business-hours interval that is abnormal for your volume.
Frequently Asked Questions
Why does signature validation suddenly fail?
Common causes are a rotated app secret, a proxy or framework that parses and re-serializes the JSON body before you hash it, or a deployment that read the wrong environment variable. Hash the raw bytes.
Should the endpoint do the real work before replying?
No. Verify the signature, store or enqueue the event, and return success quickly. Process asynchronously so slow ERP calls do not cause timeouts and retries.
How do I avoid duplicate notifications on replay?
Record the message or status ID when you process it and skip IDs you have seen. This makes replays safe after an outage.
Does this apply to Teams or Slack?
The structure transfers, but the checks differ. Teams bots depend on app registration and Azure Bot settings, and Slack depends on request signing. Adapt the triage table.
If you want help adding queue-based processing, idempotency and monitoring to a messaging integration on your own infrastructure, Netray can review your design.
Related Tools
Webhook Event Test Case Worksheet
A test plan grid for messaging webhooks: inbound text, status receipts, duplicates, bad signatures and ERP failures. Exports to Excel.
ERP OperationsMessaging Channel SLA and Escalation Worksheet
Define how fast each alert type must be acknowledged, who is escalated to and which fallback channel is used. Exports to Excel.
Developer ToolsMessaging Throughput and Rate Limit Headroom Calculator
Estimate peak message rate, how much headroom you have under a rate limit, how many workers you need and how long a burst takes to drain.
Compliance & ContractsMessaging Integration Risk Register Worksheet
A scored risk register pre-filled with typical WhatsApp, Teams and ERP chat integration risks. Edit, score and export to Excel.
More Developer Tools tools
See all- SAP Sales Order ABAP SELECT Generator (VBAK, VBAP, VBFA)
- SAP Sales Order Create BAPI ABAP Generator (BAPI_SALESORDER_CREATEFROMDAT2)
- SAP ABAP Open Items SELECT Generator
- SAP ACDOCA SQL Query Generator
- SAP QM Inspection Lot ABAP SELECT Generator
- SAP Quality Notification Pareto SQL Query Generator
- SAP QM Usage Decision BAPI Skeleton
- ABAP Custom Exception Class Generator
- ABAP Unit Test Class Generator