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、有效負載、提示或錯誤文字替換受控類別。
儲存查詢和儀表板依賴於它後就地更改欄位型別。
新增識別符號，無需記錄調查、存取和保留需求。

使用合約