Skip to content

docs: add custom headers and JWT documentation for webhooks #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jordanrendric wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add custom headers and JWT documentation for webhooks #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac91b6d
docs: add custom headers and JWT documentation for webhook endpoints
jordanrendric Mar 25, 2026
bcd12f4
docs: address review feedback - standardize param names and add jwt_k…
jordanrendric Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 40 additions & 10 deletions openapi/openapi-v2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,16 +130,14 @@
},
"headers": {
"type": "object",
"description": "Headers for send the API from webhook",
"properties": {
"authorization": {
"type": "string",
"description": "Your authorization key header"
},
"Content-Type": {
"type": "string",
"description": "content-type"
}
"description": "Custom HTTP headers sent with every webhook request. Accepts any key-value string pairs such as Authorization, X-Api-Key, or any other valid HTTP header. Special key 'jwt_key': instead of being sent as a header, its value is used as a secret to sign a JWT token (HS256, 10min expiry) that is automatically injected as 'Authorization: Bearer <token>' on each request.",
"additionalProperties": {
"type": "string"
},
"example": {
"Authorization": "Bearer your-token-here",
"X-Api-Key": "your-api-key",
"jwt_key": "your-secret-for-auto-jwt-signing"
}
},
"events": {
Expand Down Expand Up @@ -1228,6 +1226,18 @@
"type": "string",
"description": "Webhook URL"
},
"headers": {
"type": "object",
"description": "Custom HTTP headers sent with every webhook request. Accepts any key-value string pairs such as Authorization, X-Api-Key, or any other valid HTTP header. Special key 'jwt_key': instead of being sent as a header, its value is used as a secret to sign a JWT token (HS256, 10min expiry) that is automatically injected as 'Authorization: Bearer <token>' on each request.",
"additionalProperties": {
"type": "string"
},
"example": {
"Authorization": "Bearer your-token-here",
"X-Api-Key": "your-api-key",
"jwt_key": "your-secret-for-auto-jwt-signing"
}
},
"webhookByEvents": {
"type": "boolean",
"description": "Enables Webhook by events"
Expand Down Expand Up @@ -1296,6 +1306,13 @@
"type": "string",
"description": "The URL of the webhook."
},
"headers": {
"type": "object",
"description": "Custom HTTP headers configured for this webhook.",
"additionalProperties": {
"type": "string"
}
},
"events": {
"type": "array",
"items": {
Expand All @@ -1317,6 +1334,9 @@
"instanceName": "teste-docs",
"webhook": {
"url": "https://example.com",
"headers": {
"Authorization": "Bearer your-token-here"
},
"events": [
"APPLICATION_STARTUP"
],
Expand Down Expand Up @@ -1372,6 +1392,13 @@
"type": "string",
"description": "The URL of the webhook."
},
"headers": {
"type": "object",
"description": "Custom HTTP headers configured for this webhook.",
"additionalProperties": {
"type": "string"
}
},
"events": {
"type": "array",
"items": {
Expand All @@ -1383,6 +1410,9 @@
"example": {
"enabled": true,
"url": "https://example.com",
"headers": {
"Authorization": "Bearer your-token-here"
},
"events": [
"APPLICATION_STARTUP"
]
Expand Down
175 changes: 166 additions & 9 deletions v2/en/configuration/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,23 +33,172 @@ Here is an example with some common events being listened to:
"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. |
| 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](#custom-headers). |
| byEvents | boolean | No | Whether to generate a specific Webhook URL for each of your events. Returned as `webhookByEvents` in API responses. |
| base64 | boolean | No | Encode media as base64 in the webhook payload. Returned as `webhookBase64` in API responses. |
| 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/ and validate.
</Note>

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

```json POST /event/webhook/set/{instanceName}
{
"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

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

#### API Key

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

#### Basic Auth

```json
"headers": {
"Authorization": "Basic dXNlcjpwYXNzd29yZA=="
}
```

<Tip>
For Basic Auth, the value must be the `username:password` string encoded in base64.
</Tip>

#### Multiple Headers

You can combine as many headers as needed:

```json
"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:
```json
{
"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

<Warning>
The `jwt_key` value is a secret key used to sign JWT tokens. Treat it like a password: never expose it in frontend code, public repositories, or share it publicly.
</Warning>

#### Configuration

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

#### Result on each request

Every webhook request will be sent with the header:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

<Note>
The JWT token expires in **10 minutes** and is **automatically regenerated** with each event sent, ensuring your server always receives a valid token.
</Note>

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

```json
"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:

```json POST /instance/create
{
"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.
Expand All @@ -70,6 +219,11 @@ WEBHOOK_EVENTS_QRCODE_UPDATED=true
WEBHOOK_EVENTS_ERRORS=false
WEBHOOK_EVENTS_ERRORS_WEBHOOK=
```

<Warning>
The global webhook configured via environment variables **does not support custom headers**. To use headers, configure the webhook per instance via the API.
</Warning>

## Supported Events

These are the available and supported webhook events:
Expand Down Expand Up @@ -104,7 +258,7 @@ When enabling the WEBHOOK_BY_EVENTS options in both global and local webhooks, t
<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.
Expand Down Expand Up @@ -149,9 +303,12 @@ Calling the endpoint will return all information about the webhook being used by
{
"enabled": true,
"url": "[url]",
"headers": {
"Authorization": "Bearer configured-token"
},
"webhookByEvents": false,
"events": [
[events]
]
}
```
```
Loading