Webhooks

使用此端点获取有关 Mautic Webhook 的详细信息。

使用 Mautic API 库

您可以使用以下 :xref:`Mautic API Library 与此 API 进行交互，或者使用本文档中描述的各种 HTTP 端点。

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth   = new ApiAuth();
$auth       = $initAuth->newAuth($settings);
$apiUrl     = "https://example.com";
$api        = new MauticApi();
$webhookApi = $api->newApi("hooks", $auth, $apiUrl);

获取 Webhook

检索单个 Webhook。

<?php

//...
$webhook = $webhookApi->get($id);

HTTP 请求

GET /hooks/ID

响应

当请求成功检索到 Webhook 时，返回 200 OK。

{
   "hook": {
       "isPublished": true,
       "dateAdded": "2026-02-24T04:21:16+00:00",
       "dateModified": "2026-02-24T04:22:03+00:00",
       "createdBy": 1,
       "createdByUser": "John Doe",
       "modifiedBy": 1,
       "modifiedByUser": "John Doe",
       "id": 2,
       "name": "Change Contact Points",
       "description": "Change contact points.",
       "webhookUrl": "https://mysite.com/webhook/contact-points-changed",
       "secret": "mySecret",
       "eventsOrderbyDir": null,
       "category": {
           "createdByUser": "John Doe",
           "modifiedByUser": null,
           "id": 2,
           "title": "Important",
           "alias": "important",
           "description": null,
           "color": null,
           "bundle": "Webhook"
       },
       "triggers": [
           "mautic.lead_points_change"
       ]
   }
}

Webhook 属性

- Name
  - Type
  - Description
- - isPublished
  - boolean
  - Webhook 发布状态
- - dateAdded
  - datetime
  - Webhook 记录创建日期和时间
- - dateModified
  - datetime
  - Webhook 记录上次修改日期和时间
- - createdBy
  - integer
  - 创建 Webhook 记录的用户的 ID
- - createdByUser
  - string
  - 创建 Webhook 记录的用户姓名
- - modifiedBy
  - integer
  - 最后修改 Webhook 记录的用户的 ID
- - modifiedByUser
  - string
  - 最后修改此 Webhook 记录的用户姓名
- - id
  - integer
  - Webhook 的 ID
- - name
  - string
  - Webhook 名称
- - description
  - string
  - Webhook 描述
- - webhookUrl
  - string
  - 接收 Webhook 数据的 URL
- - secret
  - string
  - 用于 Webhook 身份验证或验证的密钥
- - eventsOrderbyDir
  - string
  - 事件排序方向，asc 或 desc
- - category
  - object
  - 分配给 Webhook 的类别
- - triggers
  - array
  - 触发 Webhook 的事件类型的数组

列出 Webhooks

检索 Webhook 列表。

<?php
// ...

$webhooks = $webhookApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP 请求

GET /hooks

查询参数

Name	Type	Description
`searchFilter`	string	用于过滤实体的字符串或搜索命令
`start`	integer	返回的实体起始行，默认为 0
`limit`	integer	要返回的最大实体数量，默认为 30
`orderBy`	string	用于排序的列。响应中的任何列都有效。注意: 将 camelCase 属性转换为 snake_case。例如，dateAdded 变为 date_added，webhookUrl 变为 webhook_url，依此类推。
`orderByDir`	string	排序方向，asc 或 desc
`publishedOnly`	boolean	仅返回当前已发布的实体
`minimal`	boolean	仅返回简单的映射对象，不包含其他列表

响应

当请求成功检索 Webhook 列表时，返回 200 OK。

{

“total”: 3, “hooks”: {

“2”: {
“isPublished”: true, “dateAdded”: “2026-02-24T04:21:16+00:00”, “dateModified”: “2026-02-24T04:22:03+00:00”, “createdBy”: 1, “createdByUser”: “John Doe”, “modifiedBy”: 1, “modifiedByUser”: “John Doe”, “id”: 2, “name”: “Change Contact Points”, “description”: “Change contact points.”, “webhookUrl”: “https://mysite.com/webhook/contact-points-changed”, “secret”: “mySecret”, “eventsOrderbyDir”: null, “category”: {

“createdByUser”: “John Doe”, “modifiedByUser”: null, “id”: 2, “title”: “Important”, “alias”: “important”, “description”: null, “color”: null, “bundle”: “Webhook”

}, “triggers”: [

“mautic.lead_points_change”

]

}, // …

}

}

Properties

Name	Type	Description
`total`	integer	Total count of Webhooks
`hooks`	array	A mapped collection of Webhooks indexed by their ID

For the rest of the properties, refer to Webhook properties.

Create Webhook

Creates a new Webhook.

<?php

$data = array(
    'name'        => 'test',                        // Required
    'webhookUrl'  => 'http://mysite.com/webhook/test', // Required
    'triggers'    => array(                         // Required
        'mautic.lead_post_save_new',
        'mautic.lead_post_save_update'
    ),
    'description' => 'Created via API',
    'secret'      => 'mySecret',
    'isPublished' => true,
);

$webhook = $webhookApi->create($data);

HTTP request

POST /hooks/new

POST parameters

- Name
  - Type
  - Description
- - name
  - string
  - Required.
    
    Webhook 的名称
- - webhookUrl
  - string
  - Required.
    
    接收 Webhook 负载的 URL
- - triggers
  - array
  - Required.
    
    触发 Webhook 的事件类型数组
- - description
  - string
  - Webhook 的描述
- - secret
  - string
  - 用于 Webhook 身份验证或验证的密钥
- - isPublished
  - boolean
  - Webhook 发布状态
- - eventsOrderbyDir
  - string
  - 事件排序方向，asc 或 desc
- - category
  - integer
  - 分配给 Webhook 的类别的 ID

Response

当请求成功创建 Webhook 时，返回 201 Created。

响应是一个类似于 Get Webhook 的 JSON 对象。

Properties

请参考 Webhook properties.

Edit Webhook

编辑 Webhook。

此操作支持 PUT 或 PATCH，具体取决于所需的行为：

PUT: 完全替换。如果 ID 缺失，则请求会创建一个新的 Webhook。如果 ID 存在，则请求会清除所有现有数据并用提供的值进行替换。
PATCH: 部分更新。请求仅根据请求数据更新字段值。当 Webhook ID 不存在时，请求失败。

<?php

$id   = 1;
$data = array(
    'name'        => 'test',
    'description' => 'Created via API',
    'webhookUrl'  => 'http://mysite.com/webhook/test',
    'secret'      => 'mySecret',
    'triggers'    => array(
        'mautic.lead_post_save_new',
        'mautic.lead_post_save_update'
    )
);

// 如果未找到 ID 1，则创建新的 Webhook
$createIfNotFound = true;

$webhook = $webhookApi->edit($id, $data, $createIfNotFound);

HTTP request

PUT /hooks/ID/edit: 更新现有的 Webhook，或者当 ID 不存在时创建一个新的 Webhook。
PATCH /hooks/ID/edit: 更新现有的 Webhook。当 ID 不存在时，请求失败。

POST parameters

接受与 Create Webhook 中描述的相同参数。所有参数都是可选的。

Response

PUT: 当请求成功更新 Webhook 时，返回 200 OK；当请求创建 Webhook 时，返回 201 Created。
PATCH: 当请求成功更新 Webhook 时，返回 200 OK；当 Webhook ID 不存在时，返回 404 Not Found 错误。

响应是一个类似于 Get Webhook 的 JSON 对象。

Properties

请参考 Webhook properties.

Delete Webhook

删除一个Webhook。

<?php

$webhook = $webhookApi->delete($id);

HTTP请求

DELETE /hooks/ID/delete

响应

当请求成功删除Webhook时，返回 200 OK。

响应是一个JSON对象，包含已删除Webhook的数据，类似于获取Webhook。

属性

请参考 Webhook属性。

获取Webhook触发器

检索可用的Webhook触发器列表。

<?php

$triggers = $webhookApi->getTriggers();

HTTP请求

GET /hooks/triggers

响应

当请求成功检索Webhook触发器列表时，返回 200 OK。

{

“triggers”: {

“mautic.company_post_save”: {
“label”: “Company Create/Update Event”, “description”: “Triggered when a company is created/updated”

}, “mautic.company_post_delete”: {

“label”: “Company Deleted Event”, “description”: “Triggered when a company is deleted”

}, “mautic.lead_channel_subscription_changed”: {

“label”: “Contact Channel Subscription Change Event”, “description”: “Triggered when a contact’s channel subscription status changes.”

}, “mautic.lead_company_change”: {

“label”: “Contact Company Subscription Change Event”, “description”: “Triggered when a company is added or removed to/from contact”

}, “mautic.lead_post_delete”: {

“label”: “Contact Deleted Event”, “description”: “Triggered when a contact is deleted.”

}, “mautic.lead_post_save_new”: {

“label”: “Contact Identified Event”, “description”: “Triggered when a contact is identified.”

}, “mautic.lead_points_change”: {

“label”: “Contact Points Changed Event”, “description”: “Triggered when a contact’s points are modified.”

}, “mautic.lead_list_change”: {

“label”: “Contact Segment Membership Change Event”, “description”: “Triggered when a contact segment membership is changed”

}, “mautic.lead_post_save_update”: {

“label”: “Contact Updated Event”, “description”: “Triggered when a contact is updated.”

}, “mautic.email_on_open”: {

“label”: “Email Open Event”, “description”: “mautic.email.webhook.event.open_desc”

}, “mautic.email_on_send”: {

“label”: “Email Send Event”, “description”: “mautic.email.webhook.event. send_desc”

}, “mautic.form_on_submit”: {

“label”: “Form Submit Event”, “description”: “mautic.form.webhook.event.form.submit_desc”

}, “mautic.page_on_hit”: {

“label”: “Page Hit Event”, “description”: “mautic.page.webhook.event.hit_desc”

}, “mautic.sms_on_send”: {

“label”: “Text Send Event”, “description”: “mautic.sms.webhook.event.send_desc”

}

}

}

Properties

The response contains a triggers object where each key is a trigger event type, and the value contains:

Name	Type	Description
`label`	string	Human-readable label for the trigger
`description`	string	Description of when the trigger fires