To receive messages with Evolution API you do not keep asking the API whether there is news: you set up a webhook, an address of yours that the API calls whenever something happens (a message arrived, the connection state changed). Your address receives a request with the data and decides what to do. If you are not sure what that is, start with what a webhook is and how to test it.
Event names, webhook fields and how to configure it are in the official documentation, and they depend on the version. What follows is what usually goes wrong.
Setting up the receiving side
| 1 |
Have a receiver. It can be an n8n workflow, a file on your website or an application of yours. It needs an address that Evolution API can reach. For n8n, see n8n webhooks.
|
|
| 2 |
Give the address to the instance. The documentation explains how to set each instance’s webhook and how to choose the events you want. Start with the incoming-message ones.
|
|
| 3 |
Send a test message to the linked number and check whether the receiver got the request. Save the raw content of a real message: it is the best documentation of the fields you have.
|
|
| 4 |
Answer quickly. The receiver should return success at once and do the slow work afterwards. A slow receiver brings repeats and losses.
|
|
| 5 |
Handle repeats. Any webhook system can deliver the same event twice. Keep the message identifier and ignore what you have already seen.
|
|
Why nothing arrives
| Symptom |
Likely cause |
| No request at the receiver |
The webhook is not set on that instance, the event is not selected, or the address is misspelt. |
| The receiver is on the same server and is not reached |
Inside a container, localhost is the container itself. If they share a Docker network, use the service name. If not, use the public domain. |
| It works by hand but not through the API |
In n8n, the test address only works while it is listening. The production one only answers with the workflow active. |
| Certificate error |
The receiver has an invalid or expired HTTPS. See HTTPS for a container. |
| It arrives twice |
That is normal with webhooks. Make your flow tolerate repeats. |
|
Beware of the loop. If your flow replies automatically to every message and the events include the ones you send yourself, it will answer itself forever. Filter on the direction of the message (check the real data for the field) and reply only to incoming ones. And do not reply to group messages by default.
|
Protecting the receiver
| 1 |
Use HTTPS. The message data travels in the request.
|
|
| 2 |
Put a secret in the address (a part that is hard to guess) or check, at the receiver, a value that only your API sends. Without it, anyone who finds the address can invent messages.
|
|
| 3 |
Do not trust the content. The text comes from whoever wrote it. Never execute it, and never put it into a database query untreated.
|
|
|
Before wiring a flow to real customers, let it receive for a few days and read what came in. The odd cases (images, audio, replies to messages, groups) show up quickly. For the full flow with n8n, see Evolution API with n8n.
|
|
Is the receiver on your own server and in need of HTTPS? Have a look at the VPS plans.
See VPS servers
|
RECOMMENDED PRODUCT Web hosting with cPanel Domain and SSL included, daily backups and the panel you already know. from 5.940,00 Kz/mo (3-year plan, with coupon) See plans |
Português
English
