SuperAPI AI 工具集

mailersend-webhooks

测试与质量

查看项目

更新于 10-16 05:52

技能介绍

用途:帮助开发者搭建 MailerSend Webhook 处理器,正确处理并校验收到的请求。MailerSend 是 MailerLite 旗下的事务邮件与短信 API,注意不要与 MailerLite、Mailgun、Mailchimp、Resend 混淆。

主要能力: 校验:Signature 头为原始请求体的 HMAC-SHA256 小写十六进制摘要,使用每个 Webhook 的 Signing Secret 作为密钥,无时间戳、nonce、版本前缀或字段拼接。必须使用原始字节,重新序列化 JSON 会导致校验失败。文档给出 Node 校验示例,须先比较长度再调用 crypto.timingSafeEqual(长度不匹配会抛错)。官方 Node SDK 的 MailerSendUtils.verifyWebHook() 未从包入口导出,且缺少长度保护,建议手动实现。 webhook.test ping:创建或更新 Webhook 时 MailerSend 会立即调用 URL 验证,非 2xx 则不会保存。该 ping 信封使用 message 而非 data,且用固定公开的 test_Am3L1GuOIc4blLUuHqAPxxwkZaJyEk8G 签名,Handler 需同时接受两种 secret,但仅在类型为 webhook.test 时放行,因为该 secret 公开、可被伪造,不可用于特权操作。 事件:文档列出 23 个事件,包括 activity.sent/delivered/soft_bounced/hard_bounced/opened/clicked/spam_complaint 等,sender_identity.verified、maintenance.、inbound_、email_verified、bulk_email.completed、recipient.on_hold,以及 SMS 的 sms.sent/delivered/failed。data.type 为不含前缀的活动名;data.meta 无内容时为数组 [],否则为对象;created_at 存在微秒 ISO-8601 与空格分隔两种格式,需防御式解析。

使用方式:配置环境变量 MAILERSEND_WEBHOOK_SECRET(Webhook 签名密钥,非 API Token)与 PORT。本地开发可运行 npx hookdeck-cli listen 3000 mailersend --path /webhooks/mailersend,将打印的 URL 填入 Webhook 的 URL 字段。FastAPI 示例改用 8000 端口。完整 Handler 与测试见 examples/express/、examples/nextjs/、examples/fastapi/。

限制:须在 3 秒内响应,建议立即返回 2xx 并后台处理;失败重试采用指数退避约 3 天,端点长期不可用会被自动暂停,4xx(429 除外)与 DNS 失败不重试。无重放保护材料,无法做时间戳容差校验,应基于 data.id 做应用级幂等。未提供来源 IP 白名单或 X-MailerSend-* 头,勿自行实现。具体收费与价格暂未提供。