用途:帮助搭建和调试 Mollie webhook 处理器,区分经典与新一代两套 webhook 系统,并正确处理支付状态变更。
主要能力:
- 经典 webhook:通过创建支付时的 webhookUrl 配置,请求体为 application/x-www-form-urlencoded,仅含一个 id=tr_…,不含状态。无签名,安全模型为 fetch-to-confirm:用 API key 调 GET /v2/payments/{id} 获取权威状态,不能信任请求体。
- 新一代 webhook:在 Dashboard(Developers → Webhooks)或 POST /v2/webhooks 创建订阅并指定 eventTypes,请求体为 JSON 事件对象,带 X-Mollie-Signature: sha256=<hex>,基于原始请求体做 HMAC-SHA256 验证;密钥轮换 24 小时内会发两个签名头,需拆分逗号并接受任一匹配。
使用方式:经典用 MOLLIE_API_KEY(test_ 或 live_)作为 Bearer 拉取支付;新一代用 MOLLIE_WEBHOOK_SECRET 验签后才解析 JSON。无论何种情况都应快速返回 200。本地调试可用 npx hookdeck-cli listen 3000 mollie --path /webhooks/mollie(经典)与 npx hookdeck-cli listen 3000 mollie-events --path /webhooks/mollie/events(新一代)。建议为两套系统使用不同 URL。
适用场景:支付状态跟踪(open、pending、authorized、paid、canceled、expired、failed)、退款与拒付处理(复用支付 webhook,需重新拉取)、新一代事件订阅(payment.paid、payment.authorized、payment-link.paid、sales-invoice.、payout.、balance-transaction.created 等)。
限制:经典 webhook 无签名,只能靠 fetch 确认;新一代部分事件(退款、拒付、capture、dispute、file 等)标记为 beta,需向 Mollie 支持申请;签名密钥来源文档表述不一致,需以实际设置界面为准;非 200 响应时 Mollie 约重试 26 小时,需保证幂等。具体收费、价格及其它细节暂未提供。