用途:该技能面向需要接收 Gorgias 工单事件 Webhook 的开发者,帮助搭建并加固 Webhook 处理端点。Gorgias 是电商客服系统,其对外 Webhook 通过“HTTP 集成”(Settings → Account → HTTP integration)配置:当触发某个工单事件时,Gorgias 会按你配置的请求方法、请求头和请求体模板调用你的 URL。
主要能力:
- 认证验证:Gorgias 不签名,提供两种方式:请求头认证(例如你在集成里配置 Authorization: Bearer <secret>,Gorgias 原样发送)或 OAuth2(Gorgias 用 client ID/secret 从你的 token URL 获取令牌后放入请求头或查询串)。技能给出整段请求头值的常量时间比较示例(Node.js 用 crypto.timingSafeEqual,Python 用 hmac.compare_digest),并遵循失败即拒绝原则。自定义请求头与 OAuth2 细节见参考资料 verification.md。
- 事件识别:触发点不在请求中,一个集成可监听多个触发器。建议每个触发器建一个集成,并在请求体模板里硬编码事件名(如 "event": "ticket-created"),处理器据此分发。技能列出触发键:ticket-created、ticket-updated(含标签变更)、ticket-message-created、ticket-self-unsnoozed、ticket-message-failed、ticket-assignment-updated(独占,不可与其他触发器组合)、ticket-status-updated(独占)、ticket-handed-over(仅 API,需额外配置)。
- 请求体模板:推荐以 application/json 提交,并提供模板示例,字段包括 event、ticket_id、subject、status、channel、customer_email、assignee_email、updated_datetime、message_text,变量形如 {{ticket.id}}。示例同样接受 application/x-www-form-urlencoded 及 POST、PUT、PATCH、DELETE 方法。
- 投递行为说明:5 秒超时,需快速响应、将慢任务排队;端点不可达时最多重试 3 次(10s、20s、40s),超时仅在 OAuth2 集成下重试,4xx/5xx 错误响应在两种模式下都不重试;连续失败 500 次后自动禁用,成功一次即重置计数;无投递 ID,需用 event + ticket_id + updated_datetime 去重。
使用方式:设置环境变量 GORGIAS_WEBHOOK_SECRET(未设置时示例返回 500 而非接受未认证请求);参考 examples/express/、examples/nextjs/、examples/fastapi/ 的完整处理器与测试;本地开发可用 npx hookdeck-cli listen 3000 gorgias --path /webhooks/gorgias(FastAPI 示例用 8000 端口),无需账号即可获得公网 HTTPS URL 并检查请求。生成文件时按要求添加来源注释。
适用场景:为 Gorgias 工单创建、更新、新消息、状态与分配变更等事件构建接收端点,尤其是电商客服自动化与工单同步。
限制:无 Gorgias 官方 SDK,示例直接做比较;无签名机制;无投递 ID 需自行幂等;重试有限且错误响应不重试,不能依赖重试兜底。建议搭配 webhook-handler-patterns 技能处理认证优先、解析其次、异步处理的顺序及幂等与错误处理。