检查外部集成
最后更新：2026年7月6日
服装网店"温馨衣橱"设置了一个 Webhook（当内容发生变化时向外部程序发送通知的集成），每当登记新商品，就自动把这件事通知到公司内部的提醒机器人。可是有一天，负责人说"最近新品提醒一直没收到"。首先要弄清楚：是通知真的没发出去，还是发出去了但机器人那边漏掉了。
Webhook 一旦创建好，就会自动运转，平时无需操心。但接收通知的外部程序在我们够不着的地方，总有一天会遇到它没有响应或返回错误的情况。本页面按状况分类的操作指南，讲解如何确认已设置的 Webhook 是否正常发出，以及如何找出失败的调用并根据原因加以应对。
Webhook 是什么，以及如何创建、开启、关闭和修改它，在 Webhook 中介绍。这里则专注于运营并检查已经创建好的 Webhook。
调用记录中留下了什么
每当 Webhook 向外部程序发送请求，每一次都会作为一条记录保留在调用记录中。每条记录包含以下内容。
- 何时发出，以及处理所花的时间
- 因哪种变化而发出（例如：商品登记）
- 发往了哪个地址
- 外部程序返回的响应代码（告知它如何处理了请求的结果编号）
- 这次调用是成功还是失败
调用记录分为两层。首先有一份按时间顺序浏览调用的列表，在列表中打开某一条，就会出现这次调用的详情。在详情中，可以原样查看我们实际发送的请求和外部程序返回的响应。
在 Webhook 列表中点击名称，就会打开详情画面，上方的 Webhook Calls 标签页会显示这份列表。"温馨衣橱"的 新品通知机器人 在每次商品登记时发送的记录，看起来是这样的。
列表中只简略显示 Webhook 调用时间 和 Call 结果，至于发往哪个地址、因何发送等其余信息，需要点击行打开详情才能看到。如果觉得列表内容过时，可以用右上角的 刷新 Calls 重新加载。
成功与失败由响应代码来区分。响应代码处于正常范围（大致是 200 开头和 300 开头的编号）时记为成功，其他编号则记为失败。如果外部程序完全没有响应，或返回的响应过大，这次调用也会被记为失败。
确认通知是否正常发出
要确认负责人说的是否属实，先看看这个 Webhook 至今发送的调用中有百分之多少成功了。在 Webhook 列表中就能直接看到调用成功率。
- 在服装店 Space 的设置中打开 Webhook 画面。
- 在列表中查看
新品通知机器人这一行的 成功 Calls(%) 列。
例如会显示成 "66.67%"。如果是 100%，说明至今发送的调用全部成功，那么漏掉的一方就是机器人。如果低于 100%，就意味着通知本身在发出过程中曾经受阻，下一节将查找其原因。
如果至今一条调用都没有发送过，那就不是通知失败了，而是根本没有发出。这发生在 Webhook 处于关闭状态（INACTIVE），或者在此期间没有出现符合所设条件的变化时。这时请在 Webhook 中确认它是否已开启、设定了对哪种变化作出反应。
查找失败调用的原因
看到失败时，打开那一条调用，看看哪里出了问题。详情中会同时列出我们发送的请求和外部程序返回的响应。
- 在
新品通知机器人的 Webhook Calls 标签页中，点击结果为失败的行。Webhook Call 详情 画面会打开。 - 在 请求 中确认发往了哪个地址、发送了什么内容。
- 在 响应 中确认响应代码和外部程序返回的内容。
响应代码和返回的内容会告诉你原因。如果响应代码处于失败范围，说明外部程序收到了请求，但在处理时失败了，这时返回的内容中往往写有原因。如果完全没有响应或找不到地址，可能是发送地址已更改，或者程序已停止运行。
如果想把这次调用原样转交给外部程序的负责人，可以用右上角的 复制 cURL 把它复制成可以重现这次调用的形式再发送出去。
发送的请求中也包含我们一并发送的头信息。其中被指定为机密值的（例如：连接外部程序时使用的钥匙值）会在画面上以星号遮盖显示。原始值不会暴露，可以放心查看详情。
如果这个 Webhook 同时使用了把响应回填的 WriteBack，那么每个动作是成功还是失败，也可以在同一详情的 WriteBack 结果 标签页中查看。各项的含义在 Webhook 中介绍。
失败时的应对
先要了解一点。失败的调用不会被自动重新发送。 一次失败的通知只会原样留在记录中，Webhook 不会自行重发。因此应对分为两条路。一是修复原因，让今后的通知正常发出；二是亲自处理那条已经失败、被机器人漏掉的通知。
根据在详情中看到的内容，可以排查的原因和应对如下。
| 详情中显示的内容 | 可能的原因 | 应对 |
|---|---|---|
| 失败范围的响应代码和错误内容 | 外部程序在处理请求时失败 | 把返回的响应内容原样转交给外部程序的负责人，让对方修复 |
| 没有响应或找不到地址 | 发送地址已更改，或程序已停止运行 | 确认地址是否正确，如果已更改，就修改 Webhook |
| 完全没有留下调用记录 | Webhook 已关闭（INACTIVE） | 重新开启 Webhook |
| 被记录为失败，且返回的响应非常大 | 外部程序返回的内容过大 | 调整外部程序，减少其返回的内容 |
修改地址或重新开启 Webhook 的方法，在 Webhook 中介绍。
即使修复了原因，其间已经失败的通知也不会自动重新发送。每一条失败的调用分别对应哪次商品登记，可以在该调用详情的发送内容中确认，所以对于这些商品，要直接告知机器人负责人，补上遗漏的处理。