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

# Webhook 配置

> 配置 EffiLink Webhooks 接收实时邮件事件通知。了解如何配置、载荷格式、安全最佳实践和事件类型。

Webhooks 让 EffiLink 可以近乎实时地将邮件事件数据主动推送到您自己的 HTTP 端点，无需轮询。每当发生重要事件（邮件已送达、链接被点击、收件人退订等）时，EffiLink 会将事件批量打包，以 JSON 形式 POST 到您配置的 URL。这使 Webhooks 成为构建实时看板、驱动分析管道、触发自动化流程和维护平台外审计日志的合适工具。

***

## Webhook 工作方式

1. **发生事件**：例如收件人打开一封邮件。
2. **EffiLink 批量打包事件**：为兼顾吞吐量并避免压垮您的端点，事件会被打包为每批最多 **1,000** 条推送。
3. **EffiLink POST 到您的端点**：通过 HTTPS 向您配置的回调 URL 发送 JSON 数组。
4. **您的服务器处理载荷**：解析数组并处理每个事件对象。

**请求细节**

| 项 | 值 |
| - | - |
| Method | `HTTP POST` |
| Content-Type | `application/json;charset=UTF-8` |
| User-Agent | `YiyeWebhooks` |
| 编码 | UTF-8 |
| 请求体格式 | 事件对象组成的 JSON 数组 |

***

## 配置您的 Webhook URL

### 通过控制台

最简单的方式是在 EffiLink 控制台中设置一个 **默认 Webhook URL**：

1. 进入 **设置 → Webhooks**。
2. 输入您的 HTTPS 回调 URL。
3. 选择希望接收的事件类型。
4. 将 Webhooks 切换为 **启用** 并保存。

除非被覆盖，账户中的所有发件人都会使用该 URL。

### 通过 API

使用 [Webhook 配置 API](/api/webhook-config) 以编程方式读取或更新 Webhook 设置。

**获取当前配置——`POST /v5/webhook/get`**

无需请求体，返回当前 Webhook 配置：

| 字段 | 类型 | 说明 |
| - | - | - |
| `transEvent` | object | 每种事件类型的布尔开关。键为事件名，`true` 表示已启用。 |
| `transEvent.dropped` | boolean | 是否启用 `Dropped` 事件。 |
| `transEvent.bounced` | boolean | 是否启用 `Bounced` 事件。 |
| `transEvent.delivered` | boolean | 是否启用 `Delivered` 事件。 |
| `transEvent.spamReport` | boolean | 是否启用 `SpamReport` 事件。 |
| `transEvent.opened` | boolean | 是否启用 `Opened` 事件。 |
| `transEvent.clicked` | boolean | 是否启用 `Clicked` 事件。 |
| `transEvent.unsubscribed` | boolean | 是否启用 `Unsubscribed` 事件。 |
| `transCallbackUrl` | string | 应用于所有发件人的默认回调 URL。 |
| `transCallbackUrlExtra` | array | 按发件人覆盖的 URL 列表。 |
| `transEnable` | boolean | 若为 `true`，则全局启用 Webhooks。 |

**保存配置——`POST /v5/webhook/save`**

| 参数 | 类型 | 说明 |
| - | - | - |
| `transEvent` | object | 启用或禁用各个事件类型。仅更新提供的键；未提供的键保持当前值。 |
| `transEvent.dropped` | boolean | `true` 接收 `Dropped` 事件，`false` 停止接收。 |
| `transEvent.bounced` | boolean | `true` 接收 `Bounced` 事件。 |
| `transEvent.delivered` | boolean | `true` 接收 `Delivered` 事件。 |
| `transEvent.spamReport` | boolean | `true` 接收 `SpamReport` 事件。 |
| `transEvent.opened` | boolean | `true` 接收 `Opened` 事件。 |
| `transEvent.clicked` | boolean | `true` 接收 `Clicked` 事件。 |
| `transEvent.unsubscribed` | boolean | `true` 接收 `Unsubscribed` 事件。 |
| `transCallbackUrl` | string | 默认 HTTPS 回调 URL。 |
| `transCallbackUrlExtra` | array | 按发件人覆盖的 URL 列表。每个对象格式：`{ "sender": "you@domain.com", "url": "https://..." }`。 |
| `transCallbackUrlExtraUpdateMode` | string | `"save"` 表示新增/更新条目；`"replace"` 表示替换整个按发件人列表。 |
| `transEnable` | boolean | `true` 启用，`false` 停止所有 Webhook 投递。 |

**示例：启用 delivered 与 opened 事件并设置默认 URL：**

```json theme={null}
{
  "transEvent": {
    "dropped": false,
    "bounced": false,
    "delivered": true,
    "spamReport": false,
    "opened": true,
    "clicked": false,
    "unsubscribed": false
  },
  "transCallbackUrl": "https://yourapp.com/webhooks/effilink",
  "transEnable": true
}
```

***

## Webhook 推送示例

以下是 EffiLink 投递一批事件时您的端点收到的内容。数组中可能同时包含多种事件类型。

```http theme={null}
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json;charset=UTF-8
User-Agent: YiyeWebhooks

[
  {
    "EventCode": "Delivered",
    "Email": "user@example.com",
    "EventType": "Transactional",
    "SenderEmail": "newsletter@yourcompany.com",
    "SentMailListName": "Newsletter Subscribers",
    "SubmitDateTimeV2": "2024-06-01T08:00:00Z",
    "TriggeredDateTimeV2": "2024-06-01T08:00:05Z",
    "UniqueMsgID": "msg_abc123",
    "ReceiveServer": "mx.example.com",
    "Guid": "guid_xyz789",
    "MailName": "June Newsletter"
  },
  {
    "EventCode": "Opened",
    "Email": "user@example.com",
    "EventType": "Transactional",
    "SentMailListName": "Newsletter Subscribers",
    "TriggeredDateTimeV2": "2024-06-01T09:15:22Z",
    "UniqueMsgID": "msg_abc123",
    "IP": "203.0.113.42",
    "Platform": "iOS",
    "BrowserType": "AppleMail",
    "Guid": "guid_xyz789",
    "MailName": "June Newsletter"
  }
]
```

***

## 支持的事件类型

| EventCode | 触发时机 |
| - | - |
| `Dropped` | 由于抑制过滤（退信、退订、投诉）邮件未被发送。 |
| `Bounced` | 投递失败：硬退信（永久）或软退信（临时）。 |
| `Delivered` | 邮件已被收件人邮件服务器接受。 |
| `Opened` | 收件人打开邮件。每次打开记录一次事件。 |
| `Clicked` | 收件人点击了被跟踪的链接。每次点击一次事件（需启用点击跟踪）。 |
| `Unsubscribed` | 收件人点击退订链接。 |
| `SpamReport` | 收件人将邮件标记为垃圾邮件。 |
| `TaskStatus` | 营销任务状态变化（Created 或 Completed）。 |

各事件类型的字段级完整文档请见[Webhook 事件](/zh/docs/webhook-events)。

***

## 安全注意事项

### 校验 User-Agent 请求头

EffiLink 发出的每个 Webhook 请求都包含 `User-Agent: YiyeWebhooks` 请求头。在您的端点检查该值可作为第一道防线，拒绝来自未知来源的请求。

```python theme={null}
# 示例：带 User-Agent 校验的 Flask 端点
from flask import request, abort

@app.route("/effilink/webhook", methods=["POST"])
def webhook():
    if request.headers.get("User-Agent") != "YiyeWebhooks":
        abort(403)
    events = request.get_json()
    # 处理事件...
    return "", 200
```

### 为重复投递做好准备（幂等）

如果您的端点未在预期时间内以 HTTP `2xx` 状态码响应，EffiLink 可能会重试投递。这意味着您的应用可能会多次收到同一事件。请将事件处理器设计为 **幂等**：使用 `UniqueMsgID` 结合 `EventCode` 作为复合键，在写入数据库或触发下游动作之前识别并跳过重复事件。

### 使用 HTTPS

请始终配置 HTTPS 回调 URL。不建议使用普通 HTTP 端点，未来平台版本可能会屏蔽。

### 快速响应

尽快返回 HTTP `200`，最好在任何重处理之前完成。将实际工作放入后台队列，避免端点超时进而触发重试。


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