Troubleshooting & Debugging
WhatsApp Message Status Events Not Received
Debug missing sent, delivered, read, and failed message status events in your webhook and backend processing.
Step 1
Confirm Webhooks Are Working
Webhooks are the event input for a WhatsApp integration. Meta verifies a public HTTPS callback URL, then sends incoming messages and message status events to that endpoint. Your app also needs the correct WhatsApp Business Account subscription so events reach the callback.
Implementation Checklist
- Use a public HTTPS callback and a separate verify token.
- Subscribe the app to the correct WABA and required webhook fields.
- Acknowledge events quickly and process them idempotently.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Set Up WhatsApp Webhooks.
Step 2
Confirm Status Events Are Subscribed
Cloud API message status updates arrive asynchronously through webhooks. A successful send request gives you a message ID, while later webhook events tell your application whether that message moved through sent, delivered, read, or failed states.
Store status changes against the exact WhatsApp message ID and keep the event timestamp when available. This gives you a reliable audit trail for customer support, campaign reporting, automation decisions, and debugging.
Implementation Checklist
- Persist the WhatsApp message ID returned by the send request.
- Update the matching message record instead of relying on customer phone number alone.
- Keep status processing idempotent so duplicate webhook events are safe.
- Store failure details separately from the human friendly status label.
Step 3
Check the WABA Subscription
Webhooks are the event input for a WhatsApp integration. Meta verifies a public HTTPS callback URL, then sends incoming messages and message status events to that endpoint. Your app also needs the correct WhatsApp Business Account subscription so events reach the callback.
Implementation Checklist
- Use a public HTTPS callback and a separate verify token.
- Subscribe the app to the correct WABA and required webhook fields.
- Acknowledge events quickly and process them idempotently.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Set Up WhatsApp Webhooks.
Step 4
Send A Known Test Message
Outbound messages are sent from your server to the Graph API messages endpoint for the sending Phone Number ID. Authenticate with a bearer token, validate the recipient and payload, and store the returned WhatsApp message ID so later webhook statuses can update the correct record.
Implementation Checklist
- Send from server side code, never expose the token in the browser.
- Use the Phone Number ID in the endpoint path.
- Persist the returned message ID for status tracking.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Send a WhatsApp Message With Cloud API.
Step 5
Inspect Webhook Logs
Webhooks are the event input for a WhatsApp integration. Meta verifies a public HTTPS callback URL, then sends incoming messages and message status events to that endpoint. Your app also needs the correct WhatsApp Business Account subscription so events reach the callback.
Implementation Checklist
- Use a public HTTPS callback and a separate verify token.
- Subscribe the app to the correct WABA and required webhook fields.
- Acknowledge events quickly and process them idempotently.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Set Up WhatsApp Webhooks.
Step 6
Match Message IDs
Match Message IDs should be checked with one known failing request or event. Capture the exact input, HTTP result, structured error, message ID, and relevant configuration before changing anything else. Troubleshooting becomes much faster when you can reproduce the same failure after each change.
Work from the transport layer outward: network and HTTPS, authentication, asset IDs, request payload, Meta response, webhook delivery, then your own database or CRM processing. Do not change several layers at once because a new successful result will not tell you which change fixed the original problem.
Implementation Checklist
- Reproduce the issue with one controlled test case.
- Record exact error codes and safe identifiers before editing configuration.
- Change one layer at a time and compare against a known successful baseline.
- Redact tokens and personal data from logs while keeping message IDs and event IDs for correlation.
Step 7
Check Event Processing
Debug this layer independently before changing several parts of the integration at once. Reproduce one known request or event, capture the input and output, and compare the result with what the application expected.
Use structured logs with timestamps, message IDs, event IDs, phone number IDs, and internal workflow IDs. Redact tokens and sensitive customer content. Good logs let you follow one message from API request to webhook event to CRM update without guessing which layer failed.
Implementation Checklist
- Create one repeatable test case with known input.
- Log the boundary between this layer and the next system.
- Change one variable at a time while diagnosing the failure.
- Keep a successful baseline request so future changes can be compared quickly.
Step 8
Handle Duplicate Events
Automation systems receive retries, repeated webhooks, duplicate form submissions, and updates created by their own previous actions. Without idempotency, one customer event can create multiple leads, send the same message twice, or trigger a CRM loop.
Choose a unique event or business key for each operation and store it before performing side effects. When the same event arrives again, return success or reuse the existing result instead of repeating the action. For CRM sync, also tag the source of updates so your integration can ignore changes it created itself when appropriate.
Implementation Checklist
- Use webhook event IDs, message IDs, order IDs, or form submission IDs as deduplication keys.
- Put unique constraints around records that must only exist once.
- Make retries reuse existing results instead of creating a second side effect.
- Prevent CRM update rules from triggering themselves in both directions.
Related Guides
Continue Learning
Need Implementation Help?
Need Help With Your WhatsApp or Automation Project?
If you need help building, integrating, troubleshooting, or improving a production system, you can discuss the project with me directly.