Skip to content

webhooks.mdx

Latest commit

 

History

History
310 lines (244 loc) · 12 KB

webhooks.mdx

File metadata and controls

310 lines (244 loc) · 12 KB
title Webhooks
icon webhook

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:

{
  "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.
headers object No Custom HTTP headers sent with every webhook request. See Custom Headers.
webhook_by_events boolean No Whether to generate a specific Webhook URL for each of your events.
base64 boolean No Encode media as base64 in the webhook payload.
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.

Custom Headers

You can configure custom HTTP headers that will be sent with every webhook request for the instance. This is useful for authentication, identification, and integration with external systems that require tokens or API keys.

The headers field accepts any JSON object with string key-value pairs.

Configuring Headers

{
  "webhook": {
    "enabled": true,
    "url": "https://your-endpoint.com/webhook",
    "headers": {
      "Authorization": "Bearer your-token-here",
      "X-Api-Key": "your-secret-key"
    },
    "events": [
      "MESSAGES_UPSERT",
      "CONNECTION_UPDATE"
    ],
    "byEvents": false,
    "base64": false
  }
}

Supported Authentication Types

Any valid HTTP header can be used. Below are the most common patterns:

Bearer Token

"headers": {
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
}

API Key

"headers": {
  "X-Api-Key": "your-key-here"
}

Basic Auth

"headers": {
  "Authorization": "Basic dXNlcjpwYXNzd29yZA=="
}
For Basic Auth, the value must be the `username:password` string encoded in base64.

Multiple Headers

You can combine as many headers as needed:

"headers": {
  "Authorization": "Bearer token",
  "X-Tenant-Id": "company-123",
  "X-Source": "evolution-api"
}

Automatic JWT (jwt_key)

Evolution API has a special feature for automatic JWT token generation. When you set the jwt_key key in the headers, the API will:

  1. Use the value as a secret key to sign a JWT token (HS256 algorithm)
  2. Generate a new token for each event with the following payload: 
    {
  "iat": 1711367040,
  "exp": 1711367640,
  "app": "evolution",
  "action": "webhook"
}
  3. Send the token in the Authorization: Bearer <generated_jwt> header
  4. The jwt_key itself is not sent as a header — it is removed before sending

Configuration

"headers": {
  "jwt_key": "your-secret-signing-key"
}

Result on each request

Every webhook request will be sent with the header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
The JWT token expires in **10 minutes** and is **automatically regenerated** with each event sent, ensuring your server always receives a valid token.

Validating on your server

On your server, validate the token using the same secret key configured in jwt_key with the HS256 algorithm.

You can combine jwt_key with other custom headers:

"headers": {
  "jwt_key": "secret-key",
  "X-Tenant-Id": "company-123"
}

In this case, the request will be sent with Authorization: Bearer <jwt> and X-Tenant-Id: company-123.

Headers on instance creation

You can also configure headers directly when creating an instance:

{
  "instanceName": "my-instance",
  "integration": "WHATSAPP-BAILEYS",
  "qrcode": true,
  "webhook": {
    "url": "https://your-endpoint.com/webhook",
    "headers": {
      "Authorization": "Bearer my-token"
    },
    "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
    "byEvents": false,
    "base64": false
  }
}

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.

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=
The global webhook configured via environment variables **does not support custom headers**. To use headers, configure the webhook per instance via the API.

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.

{
  "enabled": true,
  "url": "[url]",
  "headers": {
    "Authorization": "Bearer configured-token"
  },
  "webhookByEvents": false,
  "events": [
    [events]
  ]
}