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

# Вебхуки

> Получать события WhatsApp как подписанные запросы POST: конфигурация, типы событий, формат загрузки, подписи и извлечения.

GOWA отсылает JSON документ на ваш URL для каждого события WhatsApp, которое он получает: сообщения, квитанции, реакции, редактирование, удаление, набор показателей, изменение группы, ярлыки, рассылка и звонки.

Конечная дата регистрации веб-хука отсутствует. Настройте веб-хуки при запуске или на каждое устройство через `/devices/{device_id}/webhook`.

## Как работает доставка

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant WA as WhatsApp
    participant G as GOWA
    participant R as Your receiver
    WA->>G: Event (whatsmeow)
    G->>G: Skip if chat/sender matches WHATSAPP_WEBHOOK_IGNORE_JIDS
    G->>G: Resolve targets (per-device webhook or global WHATSAPP_WEBHOOK)
    G->>G: Skip target if event not in its allowlist (WHATSAPP_WEBHOOK_EVENTS)
    loop Up to 5 attempts, 10 s timeout each
        G->>R: POST JSON {event, device_id, session_id, payload}<br/>X-Hub-Signature-256: sha256=HMAC(body, secret)
        R->>R: Verify HMAC over raw body
        alt 2xx
            R-->>G: 200 OK (delivered, stop)
        else non-2xx or network error
            R-->>G: Error
            G->>G: Wait 1 s, 2 s, 4 s, then 8 s before the next attempt
        end
    end
    Note over G: After the 5th failure the event is logged and dropped
```

Каждый целевой URL доставляется самостоятельно, с собственным секретом и извлечением.

## Настроить

```bash theme={null}
# one or more URLs, comma-separated
WHATSAPP_WEBHOOK=https://example.com/wa-hook,https://backup.example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=replace-with-a-private-key # stable HMAC key
WHATSAPP_WEBHOOK_EVENTS=message,message.ack # optional allowlist; empty = all events
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us          # optional; skip chats or senders
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=false # verify HTTPS certificates
WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=false  # optional linked-device receipts
```

Флаги эквивалентности: `--webhook`, `--webhook-secret`, `--webhook-events`, `--webhook-ignore-jids`, `--webhook-insecure-skip-verify`, и `--webhook-all-device-receipts`.

Явно задайте закрытый ключ подписи. Если ключ не задан или используется старое опубликованное значение `secret`, GOWA генерирует случайный ключ, который меняется при перезапуске, и записывает предупреждение в журнал. Получателям нужен явно заданный общий ключ, чтобы проверять подписи и после перезапусков. Сертификаты HTTPS проверяются по умолчанию.

## События

| Событие | Уголен, когда |
| - | - |
| `message` | Приходит сообщение (текст, медиа, контакт, местоположение, опрос и так далее). `is_from_me` это `true` для сообщений, отправленных этим аккаунтом. |
| `message.reaction` | Кто-то реагирует на сообщение. |
| `message.revoked` | Сообщение удалено для всех. |
| `message.edited` | Сообщение отредактировано. |
| `message.ack` | Доставка или чтение квитанции (`receipt_type`: `delivered`, `read`, ...). |
| `message.deleted` | Сообщение удалено только для вас. |
| `chat_presence` | Запуск или остановка контакта вводить или записывать. |
| `presence` | Подписанный контакт идет онлайн или оффлайн. Требует наличие подписки и доступного клиента. |
| `group.participants` | Участники присоединяются, выходят, получают или теряют права администратора (`type`: `join`, `leave`, `promote`, `demote`). |
| `group.info` | Имя группы изменяется. Payload включает в себя новый файл `name` и, когда известно, `name_set_by`. |
| `group.joined` | Ваша учетная запись добавлена в группу. |
| `label.edit` | Бизнес ярлык WhatsApp создан или изменен. |
| `label.association` | Метка применена к чату или удалена из него. |
| `newsletter.joined` / `newsletter.left` | Вы подписались на канал или отписались от него. |
| `newsletter.message` | В режиме реального просмотра, вперёд и счетчик реакций для сообщений на канале. |
| `newsletter.mute` | Настройки заглушений в канале. |
| `call.offer` | Входящий вызов. С помощью `WHATSAPP_AUTO_REJECT_CALL=true` он автоматически отвергается. |
| `device.logged_out` | WhatsApp выходит из устройства, включая его причинный код. |
| `device.temporary_ban` | WhatsApp временно блокирует аккаунт. |
| `device.reachout_timelock` | WhatsApp активирует или снимает ограничения на запуск новых чатов. |

Имена событий в списке allowList не чувствительны к регистру.

## Нагрузка

Каждый запрос имеет одинаковый конверт:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_lid": "251556368777322@lid",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

| Поле | Описание |
| - | - |
| `event` | Один из названий событий выше. |
| `device_id` | JID учетной записи, которая получила событие. Пропустить события, если в слоте нет JID. |
| `session_id` | ID слота, например, ID из `POST /devices`. Автоматически созданные слоты могут использовать WhatsApp JID. События устройства всегда включают в себя ее. Другие события могут быть опущены, если JID не может быть сопоставлен с слотом. |
| `payload` | Данные о конкретных событиях. Общие поля: `id`, `chat_id`, `from`, `from_lid`, `from_name`, `sender_display_name`, `timestamp` (RFC 3339), `is_from_me`. |

Ответы добавляют `replied_to_id` и `quoted_body`. Квитанции используют `ids` (массив) и `receipt_type`. События участников группы содержат `chat_id`, `type` и `jids`. В имени группы используется отдельная форма `group.info`.

`sender_display_name` появляется только тогда, когда `from` является непустой строкой. Для другого отправителя GOWA предпочитает сохраненное имя контакта, проталкивание живого события, сохраненное имя проталкивания, а затем имя пользователя JID. Для активного аккаунта, он предпочитает push-имя аккаунта, а затем его JID идентификатор. Прекрасное решение. Старая версия `from_name` остается именем проталкивающего сообщения события.

Входящие сообщения могут включать в себя `is_business: true`, `verified_name` и `verified_level` когда WhatsApp выдаёт сертификат верифицированного имени. Иначе эти поля отсутствуют. Отсутствие не определяет, является ли отправитель бизнесом, а `verified_level` - это необработанная верхняя ценность, а не гарантия официального значения.

### Медиа

С помощью `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (по умолчанию), медиа-файлы сохраняются в папке `statics/media/`, а медиа-поле задерживает путь:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

При наличии подписи поле принимает вид `{"path": "...", "caption": "..."}`, а сама подпись также содержится в `body`. Если автоматическое скачивание отключено, поле имеет вид `{"url": "https://mmg.whatsapp.net/...", "caption": "..."}`; файл можно скачать позже с помощью `GET /message/{message_id}/download?phone=<chat>`.

Полный каталог полезных нагрузок (опросы, местонахождения, контакты, просмотр одного раза, рефералы объявлений и многое другое) находится в верхней части [ссылка на загрузку webhook приложения](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/webhook-payload.md).

## Альбомы и структурированные сообщения

Альбом поступает в виде нескольких событий `message`. Заголовок не содержит тела сообщения и передаёт ожидаемое количество элементов:

```json theme={null}
{
  "id": "ALBUM_HEADER_ID",
  "album": {
    "expected_image_count": 3,
    "expected_video_count": 1
  }
}
```

Каждое фото или видео приходит в свое собственное обычное медиа событие с `album_id: "ALBUM_HEADER_ID"`. Группировать элементы по этому ID. Заголовок не является носителем для скачивания и не пересылается в Чатвут.

Опросы, голосования, правки и добавленные опции также используют `message`. Проверяйте структурированный объект `poll`, а не полагайтесь на `body`. Опционные хэши являются хешами нижнего регистра hexadecimal SHA-256 с точными именами опций. Существующие подсказки `WHATSAPP_WEBHOOK_EVENTS=message` получают эти взаимодействия.

## Онлайн и оффлайн присутствие

Подпишитесь на каждый отдельный контакт, используя одно и то же устройство, которое принимает события:

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/user/presence/subscribe \
  -H "X-Device-Id: sales" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628987654321"}'
```

Успешный ответ содержит `results.subscribed: true` и `results.jid`. Подписка не переопределяет настройки присутствия вашего устройства. Для непрерывных обновлений запустите GOWA с:

```bash theme={null}
WHATSAPP_PRESENCE_ON_CONNECT=available
WHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_WEBHOOK_EVENTS=message,presence
```

Индикатор присутствия по умолчанию заканчивается отметкой устройства недоступным, что останавливает обновление контактного присутствия. Отметьте устройство доступным для подавления уведомлений WhatsApp во время запуска. Аккаунт для этого трейд-офф перед включением непрерывного отслеживания.

```json theme={null}
{
  "event": "presence",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:05:00Z",
  "payload": {
    "from": "628987654321@s.whatsapp.net",
    "state": "unavailable",
    "last_seen": "2026-10-29T12:04:35Z"
  }
}
```

`state` является `available` или `unavailable`. `last_seen` пропускается, когда неизвестно или скрыто в настройках конфиденциальности контакта. `from_lid` включен, когда применимо. Ввод и запись остаются отдельными событиями `chat_presence` и не используйте эту подписку.

## Изменение имени группы

```json theme={null}
{
  "event": "group.info",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T10:35:00Z",
  "payload": {
    "chat_id": "120363402106000000@g.us",
    "name": "Project team",
    "name_set_by": "628987654321@s.whatsapp.net"
  }
}
```

Разрешен `name_set_by` с LID на телефон JID, когда это возможно, и пропускается, когда WhatsApp не идентифицирует действующего лица. Подписаться на `group.info` явно если ваш список событий исключает другие события.

## Счетчик новостей

`newsletter.message` представляет счетчики живых сообщений, а не гарантированный новый пост. Записи всегда включают в себя `server_id`. `message_id`, `type` и `timestamp` пропускаются, когда WhatsApp их не предоставляет. Нулевые или отсутствующие счетчики могут быть опущены.

```json theme={null}
{
  "event": "newsletter.message",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:00:00Z",
  "payload": {
    "newsletter_id": "120363000000000000@newsletter",
    "messages": [
      {"server_id": 42, "views_count": 120, "forwards_count": 3}
    ]
  }
}
```

Когда доступно, `reaction_counts` содержит количество реакций WhatsApp. Использовать обновления по ID рассылки и ID сервера. Не используйте пропущенный счетчик как сброс к нулю.

## Ограничения аккаунта и выход

События на устройстве всегда содержат `session_id`, поэтому слоты с одним и тем же номером WhatsApp остаются отличимыми. Событие использует конфигурацию webhook слота. Удаленный выход хранит ячейку для восстановления и сообщает о личности перед выходом. Настройки слота webhook могут быть переремонтированы. Эти события не отправляются в Чатвут.

```json theme={null}
{
  "event": "device.logged_out",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "timestamp": "2026-10-29T09:00:00Z",
  "payload": {
    "code": 401,
    "reason": "logged out from another device",
    "on_connect": true
  }
}
```

| Событие | Поля полезной нагрузки |
| - | - |
| `device.logged_out` | `code`, `reason`, `on_connect`. `on_connect` отличает отказано в соединении от закрытого соединения. |
| `device.temporary_ban` | `code`, `reason`, `expires_in_seconds`. `expires_at` — расчетная RFC 3339 expiry и появляется только тогда, когда длительность является положительной. Сессия сохранена. |
| `device.reachout_timelock` | `is_active`. Необязательное поле `enforcement_type` передаёт значение WhatsApp без изменений. Необязательное поле `ends_at` содержит время окончания действия в формате RFC 3339. Значение `is_active: false` означает, что WhatsApp снял ограничение. |

Коды переадресованы без изменений и по причине из whatsmeow. Неизвестные коды все еще поступают. Только коды выхода `403` и `406` не устанавливают точную причину. Временная длительность бана 0 означает, что WhatsApp не дала срока действия. Таймер достижения ограничивает запуск новых чатов и может вызвать ошибку отправки 463.

## Проверить подписи

Каждый запрос носит `X-Hub-Signature-256: sha256=<hex>`, HMAC-SHA256 из **raw** тела запроса с ключом секрета webhook. Рассчитывает его над полученными байтами перед парсингом JSON.

```javascript Node.js (Express) theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;

app.post("/wa-hook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const signature = req.get("X-Hub-Signature-256") || "";
  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return res.sendStatus(401);
  const received = signature.slice(7);
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);            // acknowledge fast
  handle(evt);                    // then process
});
```

```python Python (Flask) theme={null}
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()

@app.post("/wa-hook")
def wa_hook():
    raw = request.get_data()
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Hub-Signature-256", "").removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        abort(401)
    evt = request.get_json()
    # enqueue evt for processing
    return "", 200
```

```go Go theme={null}
func waHook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	mac := hmac.New(sha256.New, []byte(os.Getenv("WEBHOOK_SECRET")))
	mac.Write(raw)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(r.Header.Get("X-Hub-Signature-256"), "sha256=")
	if !hmac.Equal([]byte(expected), []byte(received)) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	// process raw asynchronously
}
```

## Поставки и повторы

* Каждая попытка повторится через **10 секунд**.
* Любая не-2xx ответ или сетевая ошибка получена. GOWA состоит из **5 попыток**, ожидая между ними 1 s, 2 s, 4 и 8 сек. Обработчик событий может остановить доставку до завершения всех попыток.
* После последнего сбоя событие удаляется и регистрируется. Не существует постоянная очередь или временная буква.
* Несколько URL-адресов доставляются самостоятельно.

Ответить `2xx` после принятия события в вашу очередь прочной обработки. Сделайте идеальные обработчики, потому что проверенное событие может прибыть более одного раза.

## Квитанции на связанном устройстве

По умолчанию GOWA пересылает подтверждения от контактов только с основных устройств, чтобы сократить число дубликатов. Подтверждения `read` и `read-self` самой текущей учётной записи поступают со всех её устройств. В этих подтверждениях `payload.from` содержит JID учётной записи, а `payload.ids` указывает прочитанные входящие сообщения.

Задайте `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true` или `--webhook-all-device-receipts=true`, чтобы также получать подтверждения от контактов с привязанных устройств, в том числе когда телефон контакта не в сети. Флаг CLI имеет приоритет над переменной окружения, в том числе при явном значении `false`.

Этот отказ может генерировать повторяющиеся или устаревшие подтверждения заказа. Примените обновления idempotently на аккаунт, чат и идентификатор сообщения. ID сообщений и JID отправителя сохраняют свою каноническую форму без суффиксов устройства.

## Фильтр событий

**По типу:** `WHATSAPP_WEBHOOK_EVENTS=message,message.ack` передает только эти события.

**В чате или отправители:** `WHATSAPP_WEBHOOK_IGNORE_JIDS` соответствует `chat_id`, `from`, `chat_lid` и `from_lid`. Записи, начинающиеся с `@`, являются шаблонами для всего адресного пространства (`@g.us`, `@s.whatsapp.net`, `@lid`); все остальное — точное JID.

```bash theme={null}
# drop all group traffic plus one specific contact
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us,628123456789@s.whatsapp.net
```

`@s.whatsapp.net` также совпадает с групповыми сообщениями, потому что их `from` является пользователем JID. Используйте `@g.us`, чтобы игнорировать группы. Комбинация двух фильтров: событие отправляется только если его тип разрешён **и** его JID не игнорируется.

## Webhooks на устройство

Дайте слот своему собственному вебхуку, секретному списку и списку событий:

```bash theme={null}
curl -u admin:changeme -X PATCH http://localhost:3000/devices/sales/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sales.example.com/wa-hook",
    "webhook_secret": "sales-secret",
    "webhook_events": "message,message.ack",
    "webhook_insecure_skip_verify": false
  }'
```

Эти же поля принимаются `POST /devices`. Прочитайте текущий параметр `GET /devices/{device_id}/webhook`. Отправьте `"webhook_url": ""` чтобы очистить его.

Пустое устройство `webhook_secret` или `webhook_events` возвращается к соответствующим глобальным настройкам. Храняхранимое устройство `webhook_insecure_skip_verify` boolean заменяет глобальные настройки TLS. В частности, `false` сохраняет проверку сертификата включенной, даже если глобальный байпасс включен.

```mermaid theme={null}
flowchart TD
    A[Event for a device] --> B{Device has its own webhook_url?}
    B -- No --> G[Send to global WHATSAPP_WEBHOOK URLs<br/>global secret and allowlist]
    B -- Yes --> C{WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true?}
    C -- No --> D[Send to device URL only<br/>device secret and allowlist]
    C -- Yes --> E[Send to device URL and global URLs<br/>each with its own secret and allowlist<br/>duplicate URLs receive the event once]
```

По умолчанию URL на каждую консоль **заменяет** глобальный слот `WHATSAPP_WEBHOOK`. С помощью `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true` он **добавлен** к глобальным URL: URL-адрес устройства использует секретный и allowlist, глобальные URL-адреса сохраняют глобальные, и присутствующий в обоих случаях URL получает событие один раз. Правила Ignore-JID применяются к обоим.

## Тестирование локально

Выделите локальный приемник туннелем (например, `ngrok http 8080`) и установите `WHATSAPP_WEBHOOK` URL туннеля. С `--debug=true` GOWA записывает каждую попытку доставки и неудачу.

## Другие способы получения событий

* **[WebSocket](https://gowa-docs.mintlify.site/ru/api-reference/websocket.md)** в `/ws?device_id=<id>` выкладывает события сопряжения и состояния в рабочие столы. Используйте вебхуки для доставки сообщений.
* **Опрос:** `GET /chats` и `GET /chat/{chat_jid}/messages` читать GOWA в локальном хранилище. См. [Получение сообщений](https://gowa-docs.mintlify.site/ru/examples/receiving-messages.md).


## Related topics

- [Ссылка на конфигурацию](https://gowa-docs.mintlify.site/ru/configuration.md)
- [Получение сообщений](https://gowa-docs.mintlify.site/ru/examples/receiving-messages.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/ru/index.md)
- [Подписаться на рассылку новостей в реальном времени](https://gowa-docs.mintlify.site/ru/api-reference/newsletter/подписаться-на-рассылку-новостей-в-реальном-времени.md)
- [Лучшая практика производства](https://gowa-docs.mintlify.site/ru/advanced/best-practices.md)


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