Webhooks enable real-time integration between the Evolution API and WhatsApp™, allowing automated data synchronization and sharing.

It is exactly this feature that enables the creation of self-service bots and multi-service systems.

​
Activating webhooks

There is two ways to activate the webhook:

  • In the .env with global events
  • By calling the endpoint /webhook/instance

​
Instance webhook events

Most of the users will prefer the activation by instance, this way is easier to control the events that are received, however in some cases a global webhook is needed this could be done by using the global webhook variable.

Here is an example with some commonly listened events:

/webhook/instance
{
  "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

ParameterTypeRequiredDescription
enabledbooleanRequiredEnter “true” to create or change Webhook data, or “false” if you want to stop using it.
urlstringRequiredWebhook URL to receive event data.
webhook_by_eventsbooleanOptionalWant to generate a specific Webhook URL for each of your events.
eventsarrayOptionalList of events to be processed. If you don’t want to use some of these events, just remove them from the list.

It is extremely necessary that the payload obey the rules for creating a JSON file, considering the correct arrangement of items, formatting, square brackets, braces and commas, etc. Before consuming the endpoint, if you have questions about the JSON formatting, go to https://jsonlint.com/ and validate.

​
Global Webhook events

Each instance’s Webhook URL and events will be requested at the time it is created Define a global webhook that will listen for enabled events from all instances

.env
WEBHOOK_GLOBAL_URL=''
WEBHOOK_GLOBAL_ENABLED=false

# With this option activated, you work with a url per webhook event, respecting the global url and the name of each event
WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false

## Set the events you want to hear, all listed events 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 variableURLDescription
APPLICATION_STARTUP/application-startupNotifies you when an application startup
QRCODE_UPDATED/qrcode-updatedSends the base64 of the qrcode for reading
CONNECTION_UPDATE/connection-updateInforms the status of the connection with WhatsApp
MESSAGES_SET/messages-setSends a list of all your messages uploaded on WhatsApp. This event occurs only once
MESSAGES_UPSERT/messages-upsertNotifies you when a message is received
MESSAGES_UPDATE/messages-updateTells you when a message is updated
MESSAGES_DELETE/messages-deleteTells you when a message is deleted
SEND_MESSAGE/send-messageNotifies when a message is sent
CONTACTS_SET/contacts-setPerforms initial loading of all contacts.This event occurs only once
CONTACTS_UPSERT/contacts-upsertReloads all contacts with additional information.This event occurs only once
CONTACTS_UPDATE/contacts-updateInforms you when the chat is updated
PRESENCE_UPDATE/presence-updateInforms if the user is online, if he is performing some action like writing or recording and his last seen: ‘unavailable’, ‘available’, ‘composing’, ‘recording’, ‘paused’
CHATS_SET/chats-setSend a list of all loaded chats
CHATS_UPDATE/chats-updateInforms you when the chat is updated
CHATS_UPSERT/chats-upsertSends any new chat information
CHATS_DELETE/chats-deleteNotify you when a message is deleted
GROUPS_UPSERT/groups-upsertNotifies when a group is created
GROUPS_UPDATE/groups-updateNotifies when a group has its information updated
GROUP_PARTICIPANTS_UPDATE/group-participants-updateNotifies when an action occurs involving a participant: ‘add’, ‘remove’, ‘promote’, ‘demote’
NEW_TOKEN/new-jwtNotifies when the token (jwt) is updated

​
Webhook by events

When enabling the WEBHOOK_BY_EVENTS options in the global and local webhooks, the following paths will be added at the end of the webhook.

Add on the end of the url the event name with a dash (-) between the words that compose the event for the event.

​
Example

Assuming your webhook url was https://sub.domain.com/webhook/. Evolution will add automatically in the end of the url the name of the event when webhook_by_events is set to true.

EventNew webhook by Events URL
APPLICATION_STARTUPhttps://sub.domain.com/webhook/application-startup
QRCODE_UPDATEDhttps://sub.domain.com/webhook/qrcode-updated
CONNECTION_UPDATEhttps://sub.domain.com/webhook/connection-update
MESSAGES_SEThttps://sub.domain.com/webhook/messages-set
MESSAGES_UPSERThttps://sub.domain.com/webhook/messages-upsert
MESSAGES_UPDATEhttps://sub.domain.com/webhook/messages-update
MESSAGES_DELETEhttps://sub.domain.com/webhook/messages-delete
SEND_MESSAGEhttps://sub.domain.com/webhook/send-message
CONTACTS_SEThttps://sub.domain.com/webhook/contacts-set
CONTACTS_UPSERThttps://sub.domain.com/webhook/contacts-upsert
CONTACTS_UPDATEhttps://sub.domain.com/webhook/contacts-update
PRESENCE_UPDATEhttps://sub.domain.com/webhook/presence-update
CHATS_SEThttps://sub.domain.com/webhook/chats-set
CHATS_UPDATEhttps://sub.domain.com/webhook/chats-update
CHATS_UPSERThttps://sub.domain.com/webhook/chats-upsert
CHATS_DELETEhttps://sub.domain.com/webhook/chats-delete
GROUPS_UPSERThttps://sub.domain.com/webhook/groups-upsert
GROUPS_UPDATEhttps://sub.domain.com/webhook/groups-update
GROUP_PARTICIPANTS_UPDATEhttps://sub.domain.com/webhook/group-participants-update
NEW_TOKENhttps://sub.domain.com/webhook/new-jwt

​
Find Webhook

If necessary, there is an option to find any active webhook on the specific instance.

MethodEndpoint
GET[baseUrl]/webhook/find/[instance]

​
Data returned from the Request:

Calling the endpoint will return all the information about the webhook that is being used by the instance.

Result
{
  "enabled": true,
  "url": "[url]",
  "webhookByEvents": false,
  "events": [
    [events]
  ]
}
Available Resources