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

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.

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

Event	New Event-Specific Webhook URL
APPLICATION_STARTUP	`https://sub.domain.com/webhook/application-startup`
QRCODE_UPDATED	`https://sub.domain.com/webhook/qrcode-updated`
CONNECTION_UPDATE	`https://sub.domain.com/webhook/connection-update`
MESSAGES_SET	`https://sub.domain.com/webhook/messages-set`
MESSAGES_UPSERT	`https://sub.domain.com/webhook/messages-upsert`
MESSAGES_UPDATE	`https://sub.domain.com/webhook/messages-update`
MESSAGES_DELETE	`https://sub.domain.com/webhook/messages-delete`
SEND_MESSAGE	`https://sub.domain.com/webhook/send-message`
CONTACTS_SET	`https://sub.domain.com/webhook/contacts-set`
CONTACTS_UPSERT	`https://sub.domain.com/webhook/contacts-upsert`
CONTACTS_UPDATE	`https://sub.domain.com/webhook/contacts-update`
PRESENCE_UPDATE	`https://sub.domain.com/webhook/presence-update`
CHATS_SET	`https://sub.domain.com/webhook/chats-set`
CHATS_UPDATE	`https://sub.domain.com/webhook/chats-update`
CHATS_UPSERT	`https://sub.domain.com/webhook/chats-upsert`
CHATS_DELETE	`https://sub.domain.com/webhook/chats-delete`
GROUPS_UPSERT	`https://sub.domain.com/webhook/groups-upsert`
GROUPS_UPDATE	`https://sub.domain.com/webhook/groups-update`
GROUP_PARTICIPANTS_UPDATE	`https://sub.domain.com/webhook/group-participants-update`
NEW_TOKEN	`https://sub.domain.com/webhook/new-jwt`

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.

Result

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

Getting Started

Configuration

Integrations

Enabling Webhooks

Instance Webhook Events

Parameters

Global Webhook Events

Supported Events

Webhook by Events

Example

Locating Webhook

Data returned from the request:

​Enabling Webhooks

​Instance Webhook Events

​Parameters

​Global Webhook Events

​Supported Events

​Webhook by Events

​Example

​Locating Webhook

​Data returned from the request:

Enabling Webhooks

Instance Webhook Events

Parameters

Global Webhook Events

Supported Events

Webhook by Events

Example

Locating Webhook

Data returned from the request: