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

# Webhooks

Webhooks allow real-time integration between the l2msg WhatsApp 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

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

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

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