# WhatsApp Webhook Incident Runbook Template

> Source: https://netray.co/tools/whatsapp-webhook-incident-runbook-template
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Free Tools

## Short answer

A fill-in runbook for when WhatsApp messages stop arriving, signatures fail or delivery receipts go missing. Export to PDF or Word.

## Category

developer

## Audience

- Integration developer
- IT operations
- Support engineer

## Tool

**Kind:** template

**Output:** document

**Fields:**

#### Service name

**Key:** service

**Type:** text

**Default:** Order Status Notifier

#### Webhook endpoint URL

**Key:** endpoint

**Type:** text

**Default:** https://integrations.example.com/whatsapp/webhook

#### On-call group

**Key:** oncall

**Type:** text

**Default:** Integration on-call

#### Escalation contact

**Key:** escalation

**Type:** text

**Default:** IT Operations Manager

#### Message queue or store

**Key:** queue

**Type:** text

**Default:** Inbound event queue

#### Where app secret and token live

**Key:** secrets

**Type:** text

**Default:** Company secrets vault

#### Severity 1 definition

**Key:** sev1

**Type:** textarea

**Default:** No inbound or status events processed for more than 15 minutes during business hours, or messages sent to the wrong recipient.

#### Internal status channel

**Key:** contact_channel

**Type:** text

**Default:** #it-incidents

**Blocks:**

#### Runbook: {{service}}

**Body:** Webhook endpoint: {{endpoint}}
On-call: {{oncall}}
Escalation: {{escalation}}
Queue: {{queue}}
Secrets location: {{secrets}}
Status channel: {{contact_channel}}

#### Severity 1 Definition

**Body:** {{sev1}}

#### Triage Steps

**Table:**

**Columns:**

- Step
- Check
- Result
- Next action

**Rows:**

**0:** 1

**1:** Is the endpoint reachable over HTTPS with a valid certificate?

**0:** 2

**1:** Does the verification GET with the verify token still succeed?

**0:** 3

**1:** Are POST requests arriving? Check proxy and application logs

**0:** 4

**1:** Does signature validation of the X-Hub-Signature-256 header pass with the current app secret?

**0:** 5

**1:** Is the webhook subscription still active for the right fields?

**0:** 6

**1:** Is the queue growing or are workers failing?

**0:** 7

**1:** Has the access token expired or been revoked?

#### Recovery Actions

**Body:** 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 {{contact_channel}}.

#### Communication Log

**Table:**

**Columns:**

- Time
- Audience
- Message
- Sent by

**Rows:**

#### Post-Incident Review

**Table:**

**Columns:**

- Question
- Answer

**Rows:**

**0:** Start and end time

**0:** Root cause

**0:** Detection method and delay

**0:** Follow-up actions and owners

#### Sign-off

**Signatures:**

- Incident commander
- Service owner

**Notes:** Platform behavior, retry windows and field names change. Verify details against the current Meta documentation for your API version before relying on this runbook.

## Content

**Intro:** 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.

**Sections:**

#### How to use the runbook

**Body:** 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

**Body:** 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.

**Bullets:**

- Certificate and DNS
- Verify token and app secret
- Raw body preserved for signature check
- Subscription fields
- Queue depth and worker errors

#### Common mistakes

**Body:** 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.

**Cta:** If you want help adding queue-based processing, idempotency and monitoring to a messaging integration on your own infrastructure, Netray can review your design.

**Faq:**

#### Why does signature validation suddenly fail?

**Answer:** 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?

**Answer:** 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?

**Answer:** 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?

**Answer:** 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.

## Search terms

whatsapp webhook not receiving, whatsapp cloud api incident runbook, webhook failure runbook template, whatsapp webhook troubleshooting, integration incident runbook template, whatsapp business api support runbook

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json