Webhooks
Webhooks allow real-time integration between the Evolution API and WhatsApp™, enabling automated data synchronization and sharing.
This feature is exactly what makes it possible to create self-service bots and multi-service systems.
Enabling Webhooks
There are two ways to enable the webhook:
- In the
.envfile with global events - By calling the
/webhook/instanceendpoint
Instance Webhook Events
Most users will prefer instance-based activation, as it makes it easier to control the received events. However, in some cases, a global webhook is necessary. This can be done using the global webhook variable.
Here is an example with some common events being listened to:
{
"url": "{{webhookUrl}}",
"webhook_by_events": false,
"webhook_base64": false,
"events": [
"QRCODE_UPDATED",
"MESSAGES_UPSERT",
"MESSAGES_UPDATE",
"MESSAGES_DELETE",
"SEND_MESSAGE",
"CONNECTION_UPDATE",
"TYPEBOT_START",
"TYPEBOT_CHANGE_STATUS"
]
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| enabled | boolean | Yes | Enter “true” to create or change Webhook data, or “false” if you want to stop using it. |
| url | string | Yes | Webhook URL to receive event data. |
| webhook_by_events | boolean | No | Whether to generate a specific Webhook URL for each of your events. |
| events | array | No | List of events to be processed. If you don’t want to use some of these events, simply remove them from the list. |
It is extremely necessary that the payload follows the rules to create a JSON file, considering the correct arrangement of items, formatting, brackets, braces, commas, etc. Before consuming the endpoint, if you have doubts about the JSON formatting, go to https://jsonlint.com/ and validate.
Global Webhook Events
Each instance’s Webhook URL and events will be requested when they are created. Set up a global webhook that will listen to enabled events from all instances.
WEBHOOK_GLOBAL_URL=''
WEBHOOK_GLOBAL_ENABLED=false
# With this option enabled, you work with one URL per webhook event, respecting the global URL and each event's name
WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false
## Set the events you want to listen to; all events listed below are supported
WEBHOOK_EVENTS_APPLICATION_STARTUP=false
WEBHOOK_EVENTS_QRCODE_UPDATED=true
# Some extra events for errors
WEBHOOK_EVENTS_ERRORS=false
WEBHOOK_EVENTS_ERRORS_WEBHOOK=
Supported Events
These are the available and supported webhook events:
| Environment Variable | URL | Description |
|---|---|---|
| APPLICATION_STARTUP | /application-startup | Notifies when an application startup occurs |
| QRCODE_UPDATED | /qrcode-updated | Sends the QR code in base64 format for scanning |
| CONNECTION_UPDATE | /connection-update | Informs the status of the WhatsApp connection |
| MESSAGES_SET | /messages-set | Sends a list of all messages loaded in WhatsApp. This event occurs only once |
| MESSAGES_UPSERT | /messages-upsert | Notifies when a message is received |
| MESSAGES_UPDATE | /messages-update | Informs when a message is updated |
| MESSAGES_DELETE | /messages-delete | Informs when a message is deleted |
| SEND_MESSAGE | /send-message | Notifies when a message is sent |
| CONTACTS_SET | /contacts-set | Performs the initial loading of all contacts. This event occurs only once |
| CONTACTS_UPSERT | /contacts-upsert | Reloads all contacts with additional information. This event occurs only once |
| CONTACTS_UPDATE | /contacts-update | Informs when a contact is updated |
| PRESENCE_UPDATE | /presence-update | Informs if the user is online, performing an action such as typing or recording, and their last seen status: ‘unavailable’, ‘available’, ‘typing’, ‘recording’, ‘paused’ |
| CHATS_SET | /chats-set | Sends a list of all loaded chats |
| CHATS_UPDATE | /chats-update | Informs when a chat is updated |
| CHATS_UPSERT | /chats-upsert | Sends any new chat information |
| CHATS_DELETE | /chats-delete | Notifies when a chat is deleted |
| GROUPS_UPSERT | /groups-upsert | Notifies when a group is created |
| GROUPS_UPDATE | /groups-update | Notifies when a group has its information updated |
| GROUP_PARTICIPANTS_UPDATE | /group-participants-update | Notifies when an action occurs involving a participant: ‘add’, ‘remove’, ‘promote’, ‘demote’ |
| NEW_TOKEN | /new-jwt | Notifies when the token (jwt) is updated |
Webhook by Events
When enabling the WEBHOOK_BY_EVENTS options in both global and local webhooks, the following paths will be appended to the end of the webhook URL.
Add the event name at the end of the URL with a hyphen (-) between the words that make up the event.
Example
Suppose your webhook URL is https://sub.domain.com/webhook/. Evolution will automatically add the event name to the end of the URL when webhook_by_events is set to true.
Locating Webhook
If necessary, there is an option to locate any active webhook on the specific instance.
| Method | Endpoint |
|---|---|
| GET | [baseUrl]/webhook/find/[instance] |
Data returned from the request:
Calling the endpoint will return all information about the webhook being used by the instance.
{
"enabled": true,
"url": "[url]",
"webhookByEvents": false,
"events": [
[events]
]
}