Troubleshooting & Debugging
WhatsApp Cloud API Webhook Not Working
Troubleshoot webhook verification failures, callback configuration, missing events, payload handling, and backend processing problems.
Step 1
Confirm the Callback URL Is Public
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
Check HTTPS
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 3
Verify the GET Challenge
Verify the GET Challenge 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 4
Check the Verify Token
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 5
Confirm Webhook Fields Are Subscribed
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
Confirm the App Is Subscribed to the WABA
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 7
Inspect Post Requests
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
Check Backend Logs
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 9
Check Response Status Codes
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 10
Test With A Known Event
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.
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.