Webhook

Webhook 让你的系统能够实时响应 Warmbly 中的活动。注册一个或多个 HTTPS 端点，可按特定事件类型筛选；每当订阅事件发生时，Warmbly 会向所有匹配端点 POST 已签名的 JSON 载荷。每次投递都使用 HMAC-SHA256 签名，并携带唯一事件 ID，便于验证真实性和对重放去重。失败投递会按指数退避重试，且可查询历史进行排错。

所有 Webhook 管理端点均限定在组织范围内，并共用身份验证要求：权限范围 WEBHOOKS · 组织权限 manage_settings。签名密钥由服务器生成，仅在创建和轮换时返回，因此应立即保存。

列出 Webhook 端点

GET /webhooks

返回调用者组织配置的所有端点。响应绝不包含密钥。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

返回包含已配置 endpoints 数组的对象，不使用 data + pagination 封装。

{
  "endpoints": [
    {
      "id": "a3f1c2e4-5b6d-7e8f-9a0b-1c2d3e4f5a6b",
      "organization_id": "11111111-2222-3333-4444-555555555555",
      "url": "https://hooks.example.com/warmbly",
      "description": "Production event sink",
      "event_types": ["campaign.reply_received", "meeting.booked"],
      "enabled": true,
      "verified_at": "2026-06-11T18:02:14Z",
      "ownership_confirmed": true,
      "last_success_at": "2026-06-11T18:02:14Z",
      "last_failure_at": null,
      "last_failure_reason": null,
      "consecutive_failures": 0,
      "created_at": "2026-05-01T09:00:00Z",
      "updated_at": "2026-06-11T18:02:14Z"
    }
  ]
}

列出可用事件类型

GET /webhooks/event-types

返回 Warmbly 可发出的所有事件的标准目录。可用于构建事件类型选择器，或在写入前验证 event_types 的值。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

{
  "event_types": [
    {
      "type": "campaign.reply_received",
      "category": "campaign",
      "description": "A human reply lands for a campaign thread.",
      "firehose": false
    },
    {
      "type": "campaign.email_sent",
      "category": "campaign",
      "description": "A campaign email is dispatched by a worker.",
      "firehose": true
    }
  ]
}

firehose: true 表示高频事件。event_types 列表为空的端点不会自动接收全量事件流中的高频事件；必须在 event_types 中逐项明确列出。详情见全量事件流。

创建 Webhook 端点

POST /webhooks

创建新的订阅。此次响应是唯一一次返回签名 secret，应立即保存。URL 必须为 HTTPS，且解析到可公开路由的主机。回环、私有和链路本地目标均会被拒绝，除非服务器为本地或自托管开发启用了不安全 Webhook URL。

新端点初始处于未经验证状态，只会收到一次已签名的挑战请求，在验证通过前不会收到实际事件。参阅端点验证。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

请求体

{
  "url": "https://hooks.example.com/warmbly",
  "description": "Production event sink",
  "event_types": ["campaign.reply_received", "meeting.booked"],
  "enabled": true
}

响应

201 Created，包含完整端点对象和仅返回一次的 secret。新端点初始未经验证，verified_at 为 null；只有验证通过后才接收实时事件流。

{
  "id": "a3f1c2e4-5b6d-7e8f-9a0b-1c2d3e4f5a6b",
  "organization_id": "11111111-2222-3333-4444-555555555555",
  "url": "https://hooks.example.com/warmbly",
  "description": "Production event sink",
  "event_types": ["campaign.reply_received", "meeting.booked"],
  "enabled": true,
  "verified_at": null,
  "ownership_confirmed": false,
  "last_success_at": null,
  "last_failure_at": null,
  "last_failure_reason": null,
  "consecutive_failures": 0,
  "created_at": "2026-06-11T18:00:00Z",
  "updated_at": "2026-06-11T18:00:00Z",
  "secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0"
}

更新 Webhook 端点

PATCH /webhooks/:id

更新订阅的 URL、说明、事件筛选或启用状态。此处不修改签名密钥，需使用轮换端点。URL 和事件类型采用与创建时相同的验证规则。修改 URL 主机后，需要重新验证端点。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

请求体

结构与创建时相同。所有字段都会替换为发送的值，因此应发送完整的期望状态；event_types 会被覆盖，不会合并。

响应

200 OK，包含更新后的端点，不含密钥。

删除 Webhook 端点

DELETE /webhooks/:id

删除订阅，并级联删除其投递历史。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

204 No Content，响应体为空。

轮换签名密钥

POST /webhooks/:id/rotate-secret

签发新的签名密钥，并仅返回一次。已完成签名的在途投递在完成前仍需使用旧密钥验证，新投递则使用新密钥。轮换后应及时更新验证器。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

200 OK，包含新密钥。这是唯一一次返回该密钥。

{
  "secret": "whsec_1a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7081"
}

端点验证

POST /webhooks/:id/verify

新端点初始未经验证，通过可达性检查前不会收到实际事件。调用此端点会向目标 URL 发送一次已签名的挑战请求。端点验证后，它也可用作“发送测试事件”功能。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

质询请求

Warmbly 向端点 URL 发送 POST，携带 X-Warmbly-Event: webhook.test，请求体如下：

{
  "event_type": "webhook.test",
  "data": {
    "challenge": "whcg_...",
    "endpoint_id": "a3f1c2e4-5b6d-7e8f-9a0b-1c2d3e4f5a6b",
    "message": "This is a Warmbly webhook verification request."
  }
}

挑战使用端点密钥签名，因此可像其他投递一样验证，参阅验证签名。

响应质询

对于简单可达性检查，即在控制台注册的端点，返回任意 2xx 即可，端点会标为已验证。

对于 URL 所有权证明，OAuth 应用注册的端点必须完成此项，还需回显 challenge 值。可在 JSON 响应体中返回：

{ "challenge": "whcg_..." }

也可在响应头中返回：

X-Warmbly-Webhook-Challenge: whcg_...

修改端点 URL 的主机后，会重新启动验证要求：端点恢复为未经验证，必须再次通过挑战才能恢复接收事件。

列出所有投递记录（整个组织）

GET /webhooks/deliveries

返回组织所有端点的投递尝试，按最新优先排序。可通过查询参数缩小结果范围。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

使用标准 data + pagination 封装和不透明游标。

{
  "data": [
    {
      "id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a",
      "endpoint_id": "a3f1c2e4-5b6d-7e8f-9a0b-1c2d3e4f5a6b",
      "organization_id": "11111111-2222-3333-4444-555555555555",
      "event_type": "campaign.reply_received",
      "event_id": "e9f8a7b6-c5d4-3e2f-1a0b-9c8d7e6f5a4b",
      "status": "delivered",
      "attempt_count": 1,
      "max_attempts": 8,
      "next_attempt_at": null,
      "last_attempt_at": "2026-06-11T18:02:14Z",
      "response_status": 200,
      "response_body_excerpt": "ok",
      "error_reason": null,
      "created_at": "2026-06-11T18:02:13Z",
      "updated_at": "2026-06-11T18:02:14Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImQx...",
    "has_more": true
  }
}

列出指定端点的投递记录

GET /webhooks/:id/deliveries

返回特定端点最近的投递尝试，最新优先。每行反映对应事件在全部重试尝试中的最新状态。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

使用与组织级列表相同的 data + pagination 封装。

投递 status 为 pending、in_flight、delivered、failed 或 abandoned（重试次数耗尽）之一。response_body_excerpt 最多保留订阅者响应的前 1024 字节。

重新投递

POST /webhooks/deliveries/:deliveryId/redeliver

无论当前状态如何，都可手动将投递重新入队。适合在修复接收端后重放失败或已放弃的投递。重新投递是一轮新尝试，具有独立重试生命周期，但携带相同的 event_id，因此你的幂等键逻辑可以正确去重。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

响应

200 OK，包含更新后的投递对象。

列出因限流而丢弃的事件

GET /webhooks/throttle-drops

返回因每端点投递速率限制，或每组织、每事件类型分发限流而被抑制的事件。受限流影响的事件会在此展示，不会静默丢弃，便于监控集成处理压力，并在需要时重新投递。

身份验证：权限范围 WEBHOOKS · 组织权限 manage_settings。

投递负载

每次回调都是 HTTP POST，带有 Content-Type: application/json 请求体，结构如下：

{
  "id": "e9f8a7b6-c5d4-3e2f-1a0b-9c8d7e6f5a4b",
  "event_type": "campaign.reply_received",
  "organization_id": "11111111-2222-3333-4444-555555555555",
  "created_at": "2026-06-11T18:02:13Z",
  "data": { "...": "event-specific object" }
}

载荷中没有 version 字段。如果某种事件载荷发生不向后兼容的变更，会以新的 event_type 名称发布。现有事件类型名称绝不会原地变更版本。

收到回复事件的负载

campaign.reply_received 包含 contact_email、intent 和 confidence（基于工作区关键词列表的判读结果）、subject、snippet、action_taken、thread_id 及 email_account_id。contact_id 和 campaign_id 为可选项，仅在回复关联了对应联系人或营销活动时包含。如果收件箱标记已判断该邮件，还会携带已保存的判断结果：

{
  "ai_labels": ["Meeting", "Interested"],
  "ai_intent": "scheduling",
  "ai_intent_confidence": 0.91,
  "ai_kind": "human_reply",
  "ai_relevance": 82,
  "ai_needs_review": false
}

如果标记功能对相应判断的置信度不足，无法据此操作，ai_kind 和 ai_intent 为空字符串；如果从未判断过该邮件，则省略全部六个键。各字段含义见自动化流程。

投递请求头

每次投递均携带以下请求头：

验证签名

Warmbly 使用端点签名密钥，通过 HMAC-SHA256 为每次投递签名。X-Warmbly-Signature 请求头格式为 t=<unix-timestamp>,v1=<hex-digest>。签名字符串依次为时间戳、字面字符 .、未经改动的原始请求体。

验证步骤：

1. 从请求头解析 t 和 v1。
2. 如果 t 与当前系统时钟相差超过 5 分钟，拒绝请求。容差绝不能设为 0，否则即使晚到一秒也会导致投递失败。
3. 计算 HMAC-SHA256(secret, t + "." + rawRequestBody)，并将结果编码为十六进制。
4. 使用恒定时间比较，将你的摘要与 v1 比对，以防时序攻击。
5. 忽略所有非 v1 的方案，以防降级攻击，因为未来可能出现其他方案。

始终在任何 JSON 重新序列化之前，基于未经改动的原始请求体计算 HMAC。密钥是创建或轮换时返回的带 whsec_ 前缀的值。

# Pseudocode
signed_payload = t + "." + raw_body
expected_v1    = hex(hmac_sha256(whsec_..., signed_payload))
is_valid       = constant_time_equal(expected_v1, v1) AND abs(now() - t) < 300

Python 示例：

import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False
    if abs(time.time() - int(t)) > 300:
        return False  # replay too old
    key = secret.encode()  # whsec_... as bytes
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

使用 X-Warmbly-Event-Id 或载荷 id 字段作为幂等键，对重放去重。如果 Warmbly 收到你的 2xx 之前就触发重试，同一事件 ID 可能到达多次。

重试与退避

投递采用异步入队和消费，因此触发分发的 API 调用会立即返回，不会等待你的端点。

• 2xx 响应会将投递标为 delivered，并重置端点的失败健康状态。
• 任意非 2xx 响应，包括 3xx（绝不跟随重定向），连接错误，或超时（请求超时为 15 秒），都会将尝试标为失败并安排重试。
• 退避间隔从 30 秒开始，每次重试加倍：30 秒、1 分钟、2 分钟、4 分钟、8 分钟、16 分钟、32 分钟。后续等待上限为 1 小时。
• 默认 max_attempts 为 8。尝试次数耗尽后，投递标为 abandoned。
• 4xx 和 5xx 响应都会重试，直到尝试次数上限；4xx 也可能只是暂时的验证异常。
• 持续一段时间不断失败的端点会被自动停用，以保护第三方。接收端恢复稳定后，可在设置中重新启用。

处理程序应具有幂等性。按 X-Warmbly-Event-Id 去重，因为同一事件 ID 可能在重试中到达多次。

全量事件流

高频事件在事件目录中标有 firehose: true，且必须主动订阅。event_types 列表为空或省略的端点会订阅全部标准事件，但不会接收高频事件。要接收某个高频事件，必须明确列出：

{
  "event_types": [
    "campaign.reply_received",
    "campaign.email_sent",
    "campaign.email_opened"
  ]
}

这样可避免默认集成被发送流水线或收件箱同步产生的大量事件淹没。应有选择地订阅，并在启用前确认接收端能承受持续吞吐量。

安全

• 仅限 HTTPS：端点 URL 必须使用 https://。普通 HTTP 会在注册时被拒绝。
• SSRF 防护：对外投递具备 SSRF 防护。建立连接时会阻止私有、回环、链路本地及云元数据 IP 范围。绝不跟随重定向，只允许标准 Web 端口。
• 速率限制：每端点投递速率限制和每组织、每事件类型分发限流，同时保护你的接收端和第三方。受限流影响的事件会出现在 GET /webhooks/throttle-drops 中。
• 签名验证：始终验证 X-Warmbly-Signature 请求头。忽略它意味着任何知道端点 URL 的人都可以重放或伪造事件。

事件目录

完整目录可通过 GET /webhooks/event-types 获取。下方为按类别分组的完整参考。标为高频事件的事件必须明确订阅，参阅全量事件流。

营销活动

邮箱预热

邮件送达能力

收件箱

邮箱

联系人

CRM

自动化流程

会议

团队与访问权限

批量操作

工作区

开发者

仅用作触发器（不向外投递）

inbound.webhook 是接收入站 HTTP 请求的自动化触发器，绝不会作为对外 Webhook 事件投递。

OAuth 应用级订阅

OAuth 应用无需手动为每个组织注册端点即可接收事件。只需在应用上设置一次 webhook_url 和 webhook_events，Warmbly 就会为每个授权该应用的组织自动创建受管理端点。事件取应用声明的事件与组织已授予权限范围允许事件的交集。应用使用同一个共享的 whsec_ 密钥签署所有投递，可通过验证签名所述的相同机制验证。

四个管理端点可检查和维护应用级投递流程：查看密钥、轮换密钥、列出各组织端点及健康状态，以及分页查看跨组织投递日志。四者均需 权限范围 API_KEYS 和组织权限 manage_api_keys。完整参考见OAuth：作为应用接收事件，其中包含权限范围与事件的对应表，以及与实时网关的比较。

OAuth 应用 Webhook 域名

代表用户注册 Webhook 端点的 OAuth 应用，必须声明这些端点可使用的域名。字段位于 OAuth 应用对象的 allowed_webhook_domains，类型为字符串数组。

OAuth 应用注册的任意 Webhook 端点，其 URL 主机都必须位于应用的 allowed_webhook_domains 允许范围内。注册时会强制检查，投递时也会重新检查。allowed_webhook_domains 列表为空的应用不能注册任何 Webhook 端点。

匹配规则：

• 不带前导点的条目（acme.com）仅匹配完全相同的主机。
• 带前导点的条目（.acme.com）匹配根域名及任意子域名：acme.com、hooks.acme.com、prod.hooks.acme.com。

例如，allowed_webhook_domains 为 [".acme.com"] 时，允许 https://hooks.acme.com/warmbly，拒绝 https://otherdomain.com/warmbly。

创建或更新 OAuth 应用时设置此字段：

{
  "name": "My App",
  "allowed_webhook_domains": [".acme.com"]
}

完整的应用注册流程和字段参考见 OAuth。

从流程推送自定义数据

要将营销活动或自动化流程的自定义数据推送到端点，请添加“触发事件”操作步骤：它会发出 custom.event，由每个订阅该事件的端点接收，使用各端点自身密钥签名，并像其他投递一样重试。这样可保持统一验证模型：每个端点一份密钥，投递经过签名并支持重试。

错误

Webhook 端点采用标准错误封装，包含稳定的 code 和 request_id 字段，参阅错误码。常见情况：

• 400：载荷无效，url 非 HTTPS 或不可路由，事件类型未知，或 limit 不在 1 至 200 之间。
• 400：路径中的端点 ID 或投递 ID 无效。
• 403：OAuth 应用尝试注册的端点 URL 主机不在 allowed_webhook_domains 中。
• 404：端点或投递记录不存在，或不属于你的组织。

{
  "error": "Bad Request",
  "message": "unknown event type: campaign.exploded",
  "code": "bad_request",
  "request_id": "req_7Yc2pK1nQ4"
}