如何使用webhooks实现自定义SMS API与Mautic的集成

前置准备 #

• 完成自定义SMS API的基础调试，确保可正常调用发送接口、支持返回消息唯一ID、可推送送达/失败/回复等状态回调
• 确认所用Mautic版本为2.x及以上（该范围版本均内置Webhooks模块，无需额外安装插件）
• 开启Mautic API权限，生成调用所需的API密钥，留存Mautic站点根路径备用

核心对接流程 #

整个对接分为Mautic触发短信发送、SMS API状态回传两个双向流程：

1. Mautic侧配置Webhook触发短信发送 #

• 进入Mautic后台，依次进入「设置」-「Webhooks」-「新建」
• 基础配置项填写规则：
  • 名称自定义，建议标注用途，比如自定义SMS发送触发
  • Webhook POST URL填写自行开发的中间处理接口公网地址，必须为HTTPS协议，Mautic不支持未加密的HTTP本地地址调用
  • 触发事件选择mautic.sms_on_send，如果需要关联特定用户行为触发，可额外勾选对应联系人事件
  • 响应格式选择application/json，配置完成后保存并启用该Webhook
• 中间处理接口开发逻辑：
  接收Mautic推送的Webhook payload后，解析出收件人手机号、短信内容、Mautic短信记录ID、联系人ID四个核心字段，按照自定义SMS API的参数要求组装请求，调用发送接口。同时将SMS API返回的消息唯一ID与Mautic短信记录ID、联系人ID做关联存储，用于后续状态回调的匹配。

2. 自定义SMS API侧配置回调同步状态到Mautic #

• 在自定义SMS API的回调配置页，填写自行开发的状态回调接收接口地址，勾选需要同步的事件类型，一般包含发送成功、发送失败、用户回复三类
• 回调接收接口开发逻辑：
  解析SMS API推送的回调参数，通过消息唯一ID匹配到关联的Mautic短信记录ID、联系人ID，调用Mautic REST API PATCH /sms/{id}更新对应短信的发送状态；如果回调包含用户回复内容，可调用POST /contacts/{contactId}/notes接口将回复内容写入对应联系人的备注字段，也可触发Mautic分段规则实现后续自动化流程。

常见问题排查 #

• Mautic Webhook触发失败时，可进入Webhook详情页的「日志」标签页查看具体报错，常见问题包括POST地址不可访问、接口返回码非200、请求超时
• 状态回传Mautic失败时，优先检查API权限是否开启，请求头是否携带正确的Authorization: Bearer {API密钥}标识
• 发送失败率过高时，检查Mautic推送的手机号格式是否符合SMS API要求，Mautic默认携带国家码，可在中间处理接口做格式适配。

内容的提问来源于stack exchange，提问作者Nima Bahrami