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

# Webhooks

> 接收已签名的 HTTP POST 请求的 WhatsApp 事件：配置、事件类型、有效负载格式、签名和检索。

对于收到的每个WhatsApp事件：消息、收据，GOWA POSTs 一个 JSON 文档到您的 URL 反应、编辑、删除、输入指标、组更改、标签、通讯和通话。

没有用于注册 webhook 的端点。请在启动时配置 webhook，或通过 `/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` | 群组名称更改。有效载荷包括新的 `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 激活或取消开始新聊天的限制。 |

允许列表中的事件名称不区分大小写。

## 有效载荷

每个请求都有相同的信封：

```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，例如通过 `POST /devices` 获取的 ID。自动创建的槽位可能使用 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用户部分。 对于活跃帐户，它更喜欢帐户推送名称，然后是它的JID身份。 分辨率是最佳努力。留下的 `from_name` 仍然是消息事件推送名称。

当WhatsApp 提供验证名称证书时，传入的消息可能包括`is_business: true`、`verified_name`和`verified_level`。这些字段以其他方式被省略。 缺失并不能确定发件人是否为企业，`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 payload引用](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 对媒体项进行分组。相册头部不是可下载的媒体项，也不会转发到 Chatwoot。

投票创建、投票、编辑和添加选项也使用 `message`。检查结构化的 `poll` 对象，而不是依靠`body`。 选项哈希值是精确选项名称的小写十六进制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`。群组和频道 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 配置。 远程登出保留栏位以重新配对，并在登出前报告身份。 插件web钩子设置在重整配对后存活。这些事件不会发送到Chatwoot

```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 过期，并且只有当持续时间为正值时才会出现。会话保持不变。 |
| `device.reachout_timelock` | `is_active`。可选的 `enforcement_type` 通过 WhatsApp的值传递。可选的 `ends_at` 是一个 RFC 3339 过期。`is_active: false` 是指WhatsApp 取消了限制。 |

代码未变，原因文本来自whatsmeow。未知代码仍然存在。 仅注销代码 `403` 和 `406` 并不能确定确切的原因。 暂时禁用时间为零意味着WhatsApp 没有过期。延伸的时钟限制开始新的聊天，并可能导致发送错误463。

## 验证签名

每项请求都携带`X-Hub-Signature-256: sha256=<hex>`, 一个 **raw** 请求正文中的HMAC-SHA256用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 响应或网络错误都已被检索。 妇女事务办公室最多只能在 **5 次尝试**，在两者之间等着1 秒、2秒、4秒和8秒。 事件处理器的上下文截止日期可以在所有尝试完成之前停止送货。
* 最后一次失败后，事件被丢弃并记录。没有持久的队列或致命的商店。
* 几个URL是独立发送的。

在接受事件进入您自己的耐用处理队列后响应`2xx`。让处理器具有传染性，因为一个重试的事件可能不止一次地出现。

## 链接设备接收器

默认情况下，妇女事务办公室只是为了减少重复，从主要设备转发联系确认书。 当前账户的所有设备都传递给它自己的 `read` 和 `read-self` 收据。 对于这些自己的收据，`payload.from`是帐户JID，`payload.ids`是指已读到的收到消息。

设置 `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true` 或 `--webhook-all-device-receipts=true`，即可同时接收来自关联设备的联系人回执，包括联系人手机离线时的回执。CLI 标志会覆盖环境变量设置，显式设置为 `false` 时也不例外。

此选中可生成重复或订单以外的确认。按帐户、聊天和消息ID应用突然更新。 从不在较旧的收据到达时降级到交付。消息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 的情况下才会发送。

## 每台网络钩子

给自己的网上钩，秘密和活动允许列表：

```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` 替换了全局的 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使用设备的保密和允许列表。 全局网址保留全局网址，两个网址都接收一次事件。 对两者都适用忽略即时调试规则。

## 本地测试

通过隧道对外开放本地接收端（例如 `ngrok http 8080`），并将 `WHATSAPP_WEBHOOK` 设置为隧道 URL。启用 `--debug=true` 后，GOWA 会记录每次投递尝试及失败情况。

## 其他接收事件的方式

* **[WebSocket](https://gowa-docs.mintlify.site/zh/api-reference/websocket.md)** 在 `/ws?device_id=<id>` 中将配对和状态事件推送到仪表板客户端。使用 web钩子发送信息。
* **轮询：** `GET /chats` 和 `GET /chat/{chat_jid}/messages` 读取 GOWA 的本地聊天存储。参阅[接收消息](https://gowa-docs.mintlify.site/zh/examples/receiving-messages.md)。


## Related topics

- [Chatwoot webhook 端点](https://gowa-docs.mintlify.site/zh/api-reference/chatwoot/chatwoot-webhook-端点.md)
- [设置设备webhook 配置](https://gowa-docs.mintlify.site/zh/api-reference/device/设置设备webhook-配置.md)
- [获取设备webhook 配置](https://gowa-docs.mintlify.site/zh/api-reference/device/获取设备webhook-配置.md)
- [每台设备聊天woot webhook 端点](https://gowa-docs.mintlify.site/zh/api-reference/chatwoot/每台设备聊天woot-webhook-端点.md)
- [配置引用](https://gowa-docs.mintlify.site/zh/configuration.md)


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