概览（Overview）
打长线干异步活以及挂事件大钩子（event-driven workflows）时，这个往外喷水交件的 Webhook 就是 ModelRiver 跟你们自家大后院之间那座独木要命大桥。送单员（webhook）扑空送挂了，你们家的应用大台就成了个瞎子，根本不知道 AI 那口大锅早把饭煮熟了。所幸，请求日志（Request Logs）死死盯死了每一次的投送起落，让您能把准脉跳、火线清障。
投递走包裹的长线大生死轮（Webhook delivery lifecycle）
每一次去你们家门口塞 Webhook 包全得熬过这么一长串过鬼门关：
建了个单排上队（Planned） → 正在路上送（Delivering） → 人家收了（Success） └→ 没送进挂红（Error） → 再抢救派一单（Retry: 自动/人工） → 收了/又挂了（Success/Error）挂脸上的气色牌大解（Status meanings）
| 牌面气色（Status） | 长在哪张脸（Visual） | 啥底子意思（Meaning） |
|---|---|---|
| 排上号要送（Planned） | 挂着灰不溜秋的牌子（Gray badge） | 打包好在排队等车发件了 |
| 在道上跑（Delivering） | 挂着海水蓝的大牌（Blue badge） | 正在敲你家 HTTP 门、发着力呢 |
| 交差大吉（Success） | 亮出大绿通过牌（Green badge） | 你们家接收口痛快地退回了个 2xx 大绿标底回音 |
| 砸门外挂死（Error） | 爆出滴血大红牌（Red badge） | 送货碰壁折单了：叫你赶紧过去干预捞人 |
步步查道大探检的排查术（Step-by-step webhook monitoring）
1. 眼观一路送货大盘面（Review delivery status）
- 跨入 Request Logs（求字大总库日志），把漏斗指死在 Live mode（活跑主线） 上。
- 专门挑那些长线等差（async）单子（就是时间线里挂了 webhook delivery 下发放件这一段的单）。
- 紧盯那些在它脑门上挂着派送大果子的颜色：
- 一水绿 ✓ (Green): 顺利抵达后院交活。
- 大挂红 ✗ (Red): 扑空死了落单了：赶紧过去打捞。
2. 扒皮解剖那死单底账（Inspect failed deliveries）
戳开那个跌死没送进你们后院口的那一长拉挂单送货牌：
┌──────────────────────────────────────────────────┐│ 这趟扑空货大明细解板（Webhook Delivery Details） ││ ││ 大脸死相（Status）: Error（挂了） ││ 摸去的门牌（URL）: https://api.yourapp.com/webhooks/mr ││ 死耗了多长（Duration）: 30,012ms ││ 撞了什么鬼碰头（HTTP）: timeout（熬干拖死了） ││ 报什么案本（Error）: Request timeout after 30s（足等三十秒不给门响拉倒） ││ 啥时候走的货（Sent at）: 2 分钟前那一档 ││ 还能救得活不（Can retry）: Yes（这就大起拉还魂按钮） │└──────────────────────────────────────────────────┘3. 解尸看你原包腹内囊（Analyze the payload）
切去那个叫 Request Data（发去塞的原包裹） 的切签牌，看看你家当初到底被塞送了多胖个包：
JSON
1{2 "type": "task.completed",3 "data": {4 "channel_id": "ch_abc123",5 "request_id": "req_xyz789",6 "model": "gpt-4o",7 "provider": "openai",8 "response": {9 "choices": [10 {11 "message": {12 "role": "assistant",13 "content": "给接活大爷：这兜里装的是 AI 苦思冥想吐的大活..."14 }15 }16 ],17 "usage": {18 "prompt_tokens": 250,19 "completion_tokens": 18020 }21 }22 }23}遇着走等长线叫回音的钩子任务（event-driven workflows），这肉包里还给你明缝了一条往回喊我魂的暗线管叫 callback_url 的：
JSON
1{2 "type": "task.ai_generated",3 "data": {4 "channel_id": "ch_abc123",5 "callback_url": "https://api.modelriver.com/callbacks/cb_def456",6 "response": { ... }7 }8}4. 看你自家看门人怎么答的茬（Check your endpoint's response）
转切到 Response（回吐回的茬条） 那个签，看看你们家大门收到货后是怎么放的屁：
这叫收得顺心大圆满（Successful response）:
JSON
1{2 "status": "ok",3 "processed": true4}被你家门丁推打倒地闭门恶作剧的红错（Error response - 你们家那头炸了）:
JSON
1{2 "error": "database_connection_failed",3 "message": "没大号门牌，没法敲进你们的死库 PostgreSQL 里连上道"4}5. 起搏器拉活这些落单挂（Retry failed deliveries）
但凡投递死了并且下脚注着 can_retry（允你拉大起搏救命）标着是对的（true）：
- 在你们家后院先通开修好那个堵住不吸活的接口阀门（如果有病得先治）。
- 在刚那个坠挂包裹明细面板里，死命点下那个 Retry（起搏拉生打活 / 重新大抛试发） 按钮。
- 一道重抛的加塞急件单立马上了膛等发。
- 挂在时间走线上盯着这单重抛的新大发命。
吃死这复苏拉活抢救的红线铁规矩（Retry rules）:
- 往头死里顶天也只给 3 次搏命期（算上一开始那挂的 1 命，你还能再额外拉生 2 次重抛机会）。
- 离头一次挂盘打出必须得在 5 分内的大黄泉保命期限。
- 两次电击拉活搏命中间必须冷熬冷却过足足 30 大秒长线。
- 每电充击拉抛重救的一回都记做另起炉灶新记大盘。
常在投送抛接局大遇摔挂的死症及收解大法（Common webhook issues and solutions）
硬吃闭门大羹的门神不纳（Connection refused）
Error: connect ECONNREFUSED 10.0.0.1:443
惹了大锅病的罪原（Causes）:
- 你们家大门面服务器崩坍卧底死了，或者干脆摸不着地。
- 你们家护院放的防火墙硬生生把 ModelRiver 家的投递 IP 面门给挡杀拦墙外。
- 你们填的接收大门牌（URL）把死口端大口端口径数字敲胡弄错了。
摸出的方（Fix）: 去扒窗看看你家那破机子醒了没，验验大防火墙放行大行名单，验清楚你写进设置的大接门 URL 没有带歪音。
活活熬死的大死等拖病（Timeout）
Error: Request timeout after 30000ms（死了你还拉我等三十大秒）
这病的根处（Causes）:
- 你们家的接待口接包太慢性子，办活比老太爷还钝。
- 沉甸甸的死拽大活连带着回信一道全卡着便秘拉口。
- 写大库的数据库这头写得实在拖长拉底不见回头底耗盘空时。
大解挂之方（Fix）: 去，收到信立马抛个定心丸回敲过给 200 笑脸，接着自己猫腰后台再吃重消化：
JAVASCRIPT
1// 大赞高光活法（Good）: 只接不迟留，打个长条留步自个走在后台暗跑2app.post('/webhooks/modelriver', async (req, res) => {3 res.status(200).json({ status: 'accepted' });4 5 // 放背后自个暗自慢慢拉耗6 processWebhook(req.body).catch(console.error);7});8 9// 老套拉垮法（Bad）: 干全活累死不抬头才丢声长响10app.post('/webhooks/modelriver', async (req, res) => {11 await heavyProcessing(req.body); // 大哥你这么干非熬出个死期（timeout）不可!12 res.status(200).json({ status: 'done' });13});绿标假网黑证惹出的鬼差假印大病（SSL certificate errors）
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE
大解挂之方（Fix）: 赶紧滚去让你家安保盖公章的大证拉起活保你挂的面大金牌绿 SSL 锁是真货，别自己在家乱拿萝卜扣章挂假。
摔出来的臭嘴回票骂脏字大黑号（Non-2xx response）
HTTP Status: 500 Internal Server Error（大厂门丁给你骂了句脏的带回传丢单门退）
大解挂之方（Fix）: 赶紧回转你们家自个的大后院翻账本找你家日志看你们吐回了啥。最常见的死病：
- 压根没这条路：你们根本没开 webhook 这个接收大路由。
- 吃不下吐出了：扒那 JSON 的长皮包解析半拉报错挂。
- 硬吃吞出脑死亡：你们家办业务的大应用半中央挂挂全死机跌了。
防脱钩走死拉底看长抛全大叫那回响音（Monitoring callback status）
当你在接连事件全大流水线上的，还得挂好回回叫（callback）全音防回掉：
事件大长活流水时间全纪（Timeline for event-driven request）: ✓ AI 大脑嚼出大好活生成落盘 大告手（success） 1,200ms ✓ Webhook 放线派件递货下达 大成全（success） 45ms ? Backend 后台老总抛响回声锣 办在道上（progress） (伸脖子等着呢...)如果你们家老龟拉时超纲大期拉死底界限（整挂 5 大漫长分界）:
✓ AI 大脑嚼出大好活生成落盘 大告手（success） 1,200ms ✓ Webhook 放线派件递货下达 大成全（success） 45ms ✗ Backend 退包这大回抛不敲声 拖烂死（timeout） 300,000ms老这回叫断气掉线几大死案真由（Common callback issues）:
- 你们家后院接头人根本没扒那包看，或看了也没去扯那牵命暗线头
callback_url的管。 - 你们家消化大系统拉时超大纲脱底破 5 分挂限全拉死了时规。
- 后台把这信封往回全走扔格式错打差包格式大瞎对不拉位。
- 在你们家私院老跟 ModelRiver 这大公家扯上打拉断开没等长网路的死。
整装这沿打大线连向这跟接长行（Next steps）
- 去翻向打建长底管发件这全设大全书引（Webhooks Documentation）: 大拉门接这 webhook 放线大盘搭门引路。
- 扒线上扑街大活口挂单扫挂大盘（Debugging Production Issues）: 大实大打真走真看。
- 把所有跌盘挂错成堆当连线拔走（Troubleshooting Failures）: 成系统摸瓜拉排一切跌错底。
- 大打退回重这观大台观景总收引（Back to Observability）: 打着这退向这主大连底大台统看大首。