> ## Documentation Index
> Fetch the complete documentation index at: https://doc.evolution-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```json /webhook/instance theme={null}
{
  "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. |

> [!NOTE]
>
> 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/](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.

```bash .env theme={null}
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.

> [!NOTE]
>
> 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](https://sub.domain.com/webhook/application-startup) |
| QRCODE\_UPDATED | [https://sub.domain.com/webhook/qrcode-updated](https://sub.domain.com/webhook/qrcode-updated) |
| CONNECTION\_UPDATE | [https://sub.domain.com/webhook/connection-update](https://sub.domain.com/webhook/connection-update) |
| MESSAGES\_SET | [https://sub.domain.com/webhook/messages-set](https://sub.domain.com/webhook/messages-set) |
| MESSAGES\_UPSERT | [https://sub.domain.com/webhook/messages-upsert](https://sub.domain.com/webhook/messages-upsert) |
| MESSAGES\_UPDATE | [https://sub.domain.com/webhook/messages-update](https://sub.domain.com/webhook/messages-update) |
| MESSAGES\_DELETE | [https://sub.domain.com/webhook/messages-delete](https://sub.domain.com/webhook/messages-delete) |
| SEND\_MESSAGE | [https://sub.domain.com/webhook/send-message](https://sub.domain.com/webhook/send-message) |
| CONTACTS\_SET | [https://sub.domain.com/webhook/contacts-set](https://sub.domain.com/webhook/contacts-set) |
| CONTACTS\_UPSERT | [https://sub.domain.com/webhook/contacts-upsert](https://sub.domain.com/webhook/contacts-upsert) |
| CONTACTS\_UPDATE | [https://sub.domain.com/webhook/contacts-update](https://sub.domain.com/webhook/contacts-update) |
| PRESENCE\_UPDATE | [https://sub.domain.com/webhook/presence-update](https://sub.domain.com/webhook/presence-update) |
| CHATS\_SET | [https://sub.domain.com/webhook/chats-set](https://sub.domain.com/webhook/chats-set) |
| CHATS\_UPDATE | [https://sub.domain.com/webhook/chats-update](https://sub.domain.com/webhook/chats-update) |
| CHATS\_UPSERT | [https://sub.domain.com/webhook/chats-upsert](https://sub.domain.com/webhook/chats-upsert) |
| CHATS\_DELETE | [https://sub.domain.com/webhook/chats-delete](https://sub.domain.com/webhook/chats-delete) |
| GROUPS\_UPSERT | [https://sub.domain.com/webhook/groups-upsert](https://sub.domain.com/webhook/groups-upsert) |
| GROUPS\_UPDATE | [https://sub.domain.com/webhook/groups-update](https://sub.domain.com/webhook/groups-update) |
| GROUP\_PARTICIPANTS\_UPDATE | [https://sub.domain.com/webhook/group-participants-update](https://sub.domain.com/webhook/group-participants-update) |
| NEW\_TOKEN | [https://sub.domain.com/webhook/new-jwt](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.

```json Result theme={null}
{
  "enabled": true,
  "url": "[url]",
  "webhookByEvents": false,
  "events": [
    [events]
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.