# Webhooks

Source: https://docs.simail.ai/zh/api/webhooks/

> 读取 webhook 端点、自定义请求头的名字和投递日志。创建、修改和删除 webhook 只能由人完成。

webhook 端点由人在控制台里管理。key 可以读取它们。投递如何签名、重试和停用，见 [Webhook 指南](/zh/webhooks/)。

```json
{
  "webhook_id": "whk_01JZX4E0F1G2H3J4K5M6N7P8Q9",
  "url": "https://example.com/simail-webhook",
  "event_types": ["message.received", "thread.locked", "thread.unlocked"],
  "pod_ids": [],
  "inbox_ids": ["shop-helper@simail.email"],
  "include_non_wake": false,
  "status": "enabled",
  "disabled_reason": null,
  "client_id": null,
  "created_at": "2026-10-18T16:50:00Z",
  "updated_at": "2026-10-18T16:50:00Z"
}
```

`status` 为 `enabled`、`disabled`（人停用的）或 `auto_disabled`（`disabled_reason`：收到 `410` 后的 `gone`，或 `failing_5d`）。签名密钥永远不会返回。

## 列出和读取

`GET /v0/webhooks`

`GET /v0/webhooks/{webhook_id}`

权限 `webhook_read`。列表分页（`webhooks`）。

## 自定义请求头的名字

`GET /v0/webhooks/{webhook_id}/headers`

权限 `webhook_read`。只返回自定义请求头的**名字**（`{ "headers": ["x-team"] }`）；值加密存储，永远不返回。

## 投递日志

`GET /v0/webhooks/{webhook_id}/deliveries`

权限 `webhook_read`。每次尝试一行，最新的在前，保留 30 天：

```json
{
  "count": 1,
  "limit": 50,
  "deliveries": [
    { "event_id": "evt_01JZX4F0G1H2J3K4M5N6P7Q8R9", "event_type": "message.received", "attempt": 1, "status": "delivered", "status_code": 200, "duration_ms": 182, "error": null, "created_at": "2026-10-18T17:02:13Z" }
  ]
}
```

`status` 为 `delivered`、`failed`（还会重试）、`dead`（重试已用尽）或 `replayed`。响应正文从不存储。

## 只能由人做

`POST /v0/webhooks` · `PATCH /v0/webhooks/{webhook_id}` · `DELETE /v0/webhooks/{webhook_id}` ·
`PATCH /v0/webhooks/{webhook_id}/headers`

全部返回 `403 human_required`。测试、重放和轮换密钥也是控制台操作。这是有意的：能添加端点的 key 就可以把你的全部邮件事件转发到别处。

## 邮箱与 pod 变体

`/v0/inboxes/{inbox_id}/webhooks…` 和 `/v0/pods/{pod_id}/webhooks…` 行为相同，范围限在过滤到那个邮箱或 pod 的端点。

`/v0/webhooks/polling` 返回 `501 not_implemented`；请用 [`GET /v0/events`](/zh/events/)。