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 .env file with global events
  • By calling the /webhook/instance endpoint

​
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:

/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
enabledbooleanYesEnter “true” to create or change Webhook data, or “false” if you want to stop using it.
urlstringYesWebhook URL to receive event data.
webhook_by_eventsbooleanNoWhether to generate a specific Webhook URL for each of your events.
eventsarrayNoList 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.

.env
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 VariableURLDescription
APPLICATION_STARTUP/application-startupNotifies when an application startup occurs
QRCODE_UPDATED/qrcode-updatedSends the QR code in base64 format for scanning
CONNECTION_UPDATE/connection-updateInforms the status of the WhatsApp connection
MESSAGES_SET/messages-setSends a list of all messages loaded in WhatsApp. This event occurs only once
MESSAGES_UPSERT/messages-upsertNotifies when a message is received
MESSAGES_UPDATE/messages-updateInforms when a message is updated
MESSAGES_DELETE/messages-deleteInforms when a message is deleted
SEND_MESSAGE/send-messageNotifies when a message is sent
CONTACTS_SET/contacts-setPerforms the 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 when a contact is updated
PRESENCE_UPDATE/presence-updateInforms 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-setSends a list of all loaded chats
CHATS_UPDATE/chats-updateInforms when a chat is updated
CHATS_UPSERT/chats-upsertSends any new chat information
CHATS_DELETE/chats-deleteNotifies when a chat 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 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.

EventNew Event-Specific Webhook 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

​
Locating Webhook

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

MethodEndpoint
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.

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