用途:帮助开发者在服务端接入 Paymob webhook(交易回调),重点是 HMAC-SHA512 签名校验与交易状态判断。
主要能力:Paymob 不使用 Standard Webhooks,也不对原始请求体签名,而是对交易对象(POST 载荷中的 obj)中 20 个字段按固定顺序直接拼接(无分隔符)计算 HMAC-SHA512,十六进制编码后以回调 URL 上的 hmac 查询参数(?hmac=<hex>)传递,密钥取自 Paymob 后台。文档给出 Node 与 Python 的校验实现,并要求用 timingSafeEqual / compare_digest 做恒定时间比较。
回调类型与状态:Paymob 只有一种回调类型 TRANSACTION,没有离散事件名,需读取交易对象上的布尔字段判断结果,例如 success 为 true 且 is_refunded、is_voided、pending 均为 false 表示支付成功;success 为 false 且 error_occured 为 true 表示失败或被拒;pending 为 true 表示等待完成(如 3-D Secure);success 为 true、is_auth 为 true、is_capture 为 false 表示已授权未捕获;is_capture、is_refunded、is_voided 分别表示已捕获、已退款、已作废。回调分两种且都需在后台配置:Transaction Processed Callback 为服务端 POST,JSON 体形如 {"type":"TRANSACTION","obj":{…}},嵌套键为 obj.id、obj.order.id、obj.source_data.pan,是建议构建处理器的基础;Transaction Response Callback 为客户端跳转的 GET,参数被扁平化(id、order_id、source_data_pan 等),字段顺序与 hmac 参数相同。
使用方式:需配置环境变量 PAYMOB_HMAC_SECRET;本地开发可用 npx hookdeck-cli listen 3000 paymob --path /webhooks/paymob 建立隧道。技能附带 references/overview.md、setup.md、verification.md,以及 examples/express/、nextjs/、fastapi/ 示例。使用时要求在生成文件顶部添加注释:// Generated with: paymob-webhooks skill 与 // https://github.com/hookdeck/webhook-skills。
适用场景与限制:适用于搭建或调试 Paymob 支付回调处理,尤其是签名校验失败排查。限制与注意事项:必须按给定顺序拼接字段,并注意 JSON 布尔值在 Python 中需转为小写 true/false;应优先校验再解析并保证幂等,因为 Paymob 会重试并可能同时发送 POST 与 GET 回调。文档未提供具体价格、平台支持范围与完整生产部署步骤,此类信息暂未提供。