> ## 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.
</Note>

### 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.
</Note>

### 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]
  ]
}
```