Webhook 传送日志架构和重试字段

记录和检查什么

用于安全响应调试的 Webhook 传递日志字段

有用的交付模式标准化尝试字段，保留最终状态代码和有界响应元数据，并排除 URL、请求标头、授权、有效负载和原始响应内容。

1
交付完成
在成功或永久重试耗尽后发出一次，而不是每个日志行发出一次。
2
字段已标准化
将源字段（例如 attempt_number）映射到 attempt_count，然后保留 status_code、response_body_bytes 和列入许可名单的内容类型，而不是原始 response_body。
3
秘密不被泄露
切勿存储 request_headers、授权值、客户 URL 或 Webhook 负载。
4
测量恢复情况
按目标类型比较永久性故障、重复出现的状态代码以及重试后的恢复。

谷物

每个逻辑 Webhook 交付一个终端结果。

业主

Webhook 交付人员

何时发出

成功后或永久重试耗尽。

现场合同

字段类型和应排除的数据

在生产查询依赖现有字段名称和类型后，保持现有字段名称和类型稳定。可选上下文应受到特定决策的限制、记录和证明。

字段	类型	必填	隐私	含义
timestamp_utc	timestamp	yes	non-sensitive	结果边界处的 UTC 时间。
event_id	string	yes	non-sensitive	用于重复数据删除的稳定唯一标识符。
release	string	yes	non-sensitive	发出事件的应用程序或服务版本。
account_id	string	yes	pseudonymous	稳定的内部帐户标识符，绝不是电子邮件或姓名。
delivery_id	string	yes	pseudonymous	稳定的逻辑交付标识符。
destination_type	string	yes	non-sensitive	有界集成类别，而不是目标 URL。
attempt_count	number	yes	non-sensitive	尝试最终的结果。
status_code	number	no	non-sensitive	存在响应时的最终 HTTP 状态。
response_body_bytes	number	no	non-sensitive	最终响应主体大小（以字节为单位）。存储大小而不是响应正文。
response_content_type	string	no	review	列入白名单的响应媒体类型，例如 application/json；切勿复制不受限制的响应标头。
status	string	yes	non-sensitive	已交付或永久失败。

合成 JSON 事件

{
  "timestamp_utc": "2026-07-28T14:29:08Z",
  "event_id": "evt_webhook_01",
  "account_id": "acct_8f31",
  "release": "2026.07.2",
  "delivery_id": "delivery_09cc",
  "destination_type": "slack",
  "attempt_count": 1,
  "status_code": 200,
  "response_body_bytes": 27,
  "response_content_type": "application/json",
  "status": "delivered"
}

隐私审查

摄取前检查标识符

此示例使用合成标识符。假名值仍然可以是个人数据，并且审核字段可以公开业务或提供商上下文。应用您自己的同意、保留、访问、居住和删除要求。

account_id: pseudonymous
delivery_id: pseudonymous
response_content_type: review

验证清单

在构建仪表板之前证明合同

Send one known webhook_delivery_completed fixture after the documented outcome boundary.
Verify all 8 required fields arrive with the documented types.
重试相同的事件标识符并确认所选的重复数据删除行为。
当工作流支持时，发送受控失败或替代结果。
在固定窗口上运行相关 SQL 并将结果与固定装置进行协调。

常见错误

保持一行等于一个持久结果

Emitting webhook_delivery_completed before webhook delivery worker knows the final outcome.
在一张表中混合多种谷物，这使得计数和比率不明确。
用原始 URL、有效负载、提示或错误文本替换受控类别。
保存查询和仪表板依赖于它后就地更改字段类型。
添加标识符，无需记录调查、访问和保留需求。

使用合同