Getting started with Webhooks

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以在 Mautic Developer Documentation archived repository 中访问它。

如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。

Webhook 是一种通用的方法，用于将有关联系人和其活动的数据以实时方式（即在发生更改/活动时）或批量方式（通过后台 Cron 作业发送）发送到第三方。

Webhook 的有效负载结构如下。WebhookEventType 是事件的实际类型，WebhookEventPayload 包含事件的数据。

{
    "WebhookEventType": [
        { WebhookEventPayload }
    ]
}

当使用 Background workflow 时，Mautic 会聚合事件类型和有效负载。

{
    "WebhookEventType1": [
        { WebhookEventPayload1 },
        { WebhookEventPayload2 },
        { WebhookEventPayload3 }
    ],
    "WebhookEventType2": [
        { WebhookEventPayload4 },
        { WebhookEventPayload5 },
        { WebhookEventPayload6 }
    ]
}

请参阅 Webhook events and payloads 以获取事件类型及其有效负载结构的列表。

Webhook 工作流

以下示例工作流描述了如何使用 Webhook 的示例。

假设您有一个项目管理系统 (PMS)，并且希望在联系人提交表单时创建一个新的问题。

实时工作流

联系人提交 Mautic 表单。
Mautic 保存表单提交。
Mautic 检查是否存在具有表单提交事件的 Webhook。
如果存在，Mautic 会根据有效负载的原始正文和密钥生成 Webhook-Signature 头，然后将数据传递到 Webhook 中定义的 URL 地址。
PMS 接收数据并从中创建一个新的问题。

后台工作流

联系人提交 Mautic 表单。
Mautic 保存表单提交。
Mautic 检查是否存在具有表单提交事件的 Webhook。
如果存在，Mautic 会将该事件放入数据库队列中。
当后台 cron 作业运行时，Mautic 会聚合这些事件，根据有效负载的原始正文和密钥生成 Webhook-Signature 头，然后将数据传递到 Webhook 中定义的 URL 地址。
PMS 接收数据并从中创建新的问题。

配置 Webhooks

编辑 Mautic 的配置以更改某些与 Webhook 相关的行为。

从管理菜单点击 Configuration，该菜单位于右上角的齿轮图标下。
点击 Webhook Settings 选项卡。
根据以下定义修改设置。
点击 Save & Close 或 Apply

队列模式

配置 Mautic 如何传递事件。选项如下：

Process Events Immediately - 实时传递单个事件

Queue Events Only - Process Via CLI Command - 将事件排队到数据库，并使用 :xref:`Webhook Cron Job 以批次方式传递

已排队的事件顺序

配置当事件以批处理方式进行队列时，事件的顺序。选项如下：

Chronological - 从最早到最新排序

Reverse Chronological - 从最新到最早排序

创建 Webhook

每个应用程序或脚本都应该配置自己的 Webhook，以尽量减少暴露 :ref:`secret key<webhooks/getting_started:Securing a Webhook> 的地方。

从管理菜单点击 Webhooks，该菜单位于右上角的齿轮图标下。
点击 New。
填写名称、Webhook POST URL，并选择应触发此 Webhook 的事件。您还可以自定义签名（如果需要），或者将其保留为默认值，该默认值是独一无二且随机生成的。
点击 Apply。
Test the Webhook。

测试 Webhook

如果您还没有地方发送 Webhook，可以使用像 :xref:`RequestBin 这样的服务。

如果按照说明进行操作以 create a Webhook，您应该在编辑 Webhook 的表单中。否则，请转到管理菜单中的 Webhooks，点击 Webhook，然后点击 Edit。

在编辑 Webhook 时，您应该会看到一个 Send Test Payload 按钮。点击它，Mautic 会将示例请求发送到配置的 POST URL。

您还可以通过测试 Mautic 中的实时工作流程来测试 Webhook。

保护 Webhook

Mautic 根据请求的原始内容和在创建 Webhook 时可配置的密钥，生成一个 base64 编码的 HMAC-SHA256 签名。它将该签名设置为发送到第三方应用程序的请求的 Webhook-Signature 标头的 value。应用程序应基于接收到的请求的原始内容以及密钥，生成自己的 base64 编码的 HMAC-SHA256 签名，然后将其与 Webhook-Signature 标头的值进行比较。

Warning

只有 Mautic 和应用程序应该知道密钥。

Warning

请忽略签名不匹配的请求，因为它们是不安全的。