To receive messages from the WhatsApp Cloud API, Meta has to know where to send them. You give it an address, Meta verifies it once, and from then on calls it whenever a message arrives or the status of one you sent changes. If the check fails, Meta does not save the address. Nearly every problem is there, and nearly all of them come down to the address, the HTTPS or what the server returns.
What Meta asks of your address
| Requirement |
Why |
| Public, with valid HTTPS |
Meta does not call local addresses or ones with an invalid certificate. See HTTPS for a container. |
| Answer the verification |
It is a test request carrying a challenge and your secret word. The server compares the word and returns the challenge, exactly as Meta’s documentation describes. |
| Return success quickly |
For real messages, Meta expects a fast success response. If it does not get one, it tries again. |
| Accept repeats |
The same notification can arrive more than once. |
Step by step
| 1 |
Build the receiver. It can be an n8n workflow (see n8n webhooks), a file of yours on the server, or an application. It must be reachable over HTTPS.
|
|
| 2 |
Choose the verify token. It is a secret word of yours, and not the API token. Write it into the receiver.
|
|
| 3 |
Code the answer to the verification. When Meta makes the test request, the receiver compares the word and returns the challenge it received. The documentation shows the request and the response.
|
|
| 4 |
Enter the address and the word in the app dashboard, in the WhatsApp section, and ask for verification.
|
|
| 5 |
Subscribe to the fields you need, such as the messages one. Without that, the check passes and nothing ever arrives.
|
|
| 6 |
Message the number and see whether the request reaches the receiver. Save the content: it is the best documentation of the fields.
|
|
|
Check who is writing to you. The address is public, so anyone can send requests that look like Meta’s. Meta signs every notification with your app’s secret, and the documentation names the header and how to compute the signature. Validate it and reject whatever does not match.
|
Why verification fails
| Symptom |
Likely cause |
| Meta cannot reach the address |
Firewall, closed port, a domain that does not resolve, or an invalid or expired certificate. |
| The request arrives but is refused |
The secret word does not match, or the receiver does not return the challenge exactly as received. |
| Verification passes and no messages arrive |
You did not subscribe to the messages field, or the app is in test mode with the test number. |
| It works and then stops |
The certificate expired, or the receiver got slow and Meta gave up. |
| Duplicates arrive |
That is normal. Keep the message identifier and ignore what you have already handled. |
After receiving
| 1 |
Answer the webhook first, and handle the message afterwards.
|
|
| 3 |
Log what comes in for a while, to find the odd cases.
|
|
RECOMMENDED PRODUCT Web hosting with cPanel Domain and SSL included, daily backups and the panel you already know. from KSh858.00/mo (3-year plan, with coupon) See plans |
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
