钩子 Webhooks

Strapi webhook 是用户定义的 HTTP 回调，应用程序使用它来通知其他应用程序事件发生了。

Webhook 是应用程序用来通知其他应用程序事件发生的结构。更准确地说，webhook 是用户定义的 HTTP 回调。使用 webhook 是告知第三方提供商开始某些处理（CI、构建、部署...）的好方法。

webhook 的工作方式是通过 HTTP 请求（通常是 POST 请求）将信息传递给接收应用程序。

用户内容类型 webhook

为防止无意中将任何用户的信息发送到其他应用程序，Webhook 不适用于用户内容类型。 如果您需要通知其他应用程序有关用户集合中的更改，您可以使用 ./src/index.js 示例创建 生命周期钩子 来实现。

可用配置

您可以在文件 ./config/server 中设置 webhook 配置。

  • webhooks
  • defaultHeaders：您可以设置用于 webhook 请求的默认标头。此选项将被 webhook 本身中设置的标头覆盖。

示例配置

js
JavaScript
js
// ./config/server.js
module.exports = {
  webhooks: {
    defaultHeaders: {
      'Custom-Header': 'my-custom-header',
    },
  },
}

保护您的 webhook

大多数情况下，webhook 会向公共 URL 发出请求，因此有人可能会找到该 URL 并向其发送错误的信息。

为了防止这种情况发生，您可以发送带有身份验证令牌的标头。使用管理面板，您必须为每个 webhook 执行此操作。 另一种方法是定义“defaultHeaders”以添加到每个 webhook 请求中。

您可以通过更新“./config/server”中的文件来配置这些全局标头：

Simple token

js
./config/server.js
js
module.exports = {
  webhooks: {
    defaultHeaders: {
      Authorization: 'Bearer my-very-secured-token',
    },
  },
}

Environment variable

js
./config/server.js
js
module.exports = {
  webhooks: {
    defaultHeaders: {
      Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
    },
  },
}

如果您自己开发 webhook 处理程序，您现在可以通过读取标题来验证令牌。

可用事件

默认情况下，Strapi webhook 可以由以下事件触发：

名称说明
entry.create当创建内容类型条目时触发。
entry.update当更新内容类型条目时触发。
entry.delete当删除内容类型条目时触发。
entry.publish当发布内容类型条目时触发。*
entry.unpublish当取消发布内容类型条目时触发。*
media.create当创建媒体时触发。
media.update当更新媒体时触发。
media.delete删除媒体时触发。
review-workflows.updateEntryStage在审核阶段之间移动内容时触发（请参阅 审核工作流程)。
此事件仅适用于 企业版
releases.publish发布版本时触发（请参阅 发布)。
此事件仅适用于 企业版
  • 仅当在此内容类型上启用 draftAndPublish 时。

有效载荷

私有字段和密码不会在有效载荷中发送。

Headers

当有效负载传递到您的 webhook 的 URL 时，它将包含特定的标头：

标头说明
X-Strapi-Event触发的事件类型的名称。

entry.create

创建新条目时会触发此事件。

示例有效负载

json
{
  "event": "entry.create",
  "createdAt": "2020-01-10T08:47:36.649Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "createdAt": "2020-01-10T08:47:36.264Z",
    "updatedAt": "2020-01-10T08:47:36.264Z",
    "cover": null,
    "images": []
  }
}

entry.update

更新条目时会触发此事件。

Example payload

json
{
  "event": "entry.update",
  "createdAt": "2020-01-10T08:58:26.563Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "createdAt": "2020-01-10T08:47:36.264Z",
    "updatedAt": "2020-01-10T08:58:26.210Z",
    "cover": null,
    "images": []
  }
}

entry.delete

删除条目时会触发此事件。

Example payload

json
{
  "event": "entry.delete",
  "createdAt": "2020-01-10T08:59:35.796Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "createdAt": "2020-01-10T08:47:36.264Z",
    "updatedAt": "2020-01-10T08:58:26.210Z",
    "cover": null,
    "images": []
  }
}

entry.publish

发布条目时会触发此事件。

Example payload

json
{
  "event": "entry.publish",
  "createdAt": "2020-01-10T08:59:35.796Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "createdAt": "2020-01-10T08:47:36.264Z",
    "updatedAt": "2020-01-10T08:58:26.210Z",
    "publishedAt": "2020-08-29T14:20:12.134Z",
    "cover": null,
    "images": []
  }
}

entry.unpublish

取消发布条目时会触发此事件。

Example payload

json
{
  "event": "entry.unpublish",
  "createdAt": "2020-01-10T08:59:35.796Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "createdAt": "2020-01-10T08:47:36.264Z",
    "updatedAt": "2020-01-10T08:58:26.210Z",
    "publishedAt": null,
    "cover": null,
    "images": []
  }
}

media.create

在创建条目时或通过媒体界面上传文件时会触发此事件。

Example payload

json
{
  "event": "media.create",
  "createdAt": "2020-01-10T10:58:41.115Z",
  "media": {
    "id": 1,
    "name": "image.png",
    "hash": "353fc98a19e44da9acf61d71b11895f9",
    "sha256": "huGUaFJhmcZRHLcxeQNKblh53vtSUXYaB16WSOe0Bdc",
    "ext": ".png",
    "mime": "image/png",
    "size": 228.19,
    "url": "/uploads/353fc98a19e44da9acf61d71b11895f9.png",
    "provider": "local",
    "provider_metadata": null,
    "createdAt": "2020-01-10T10:58:41.095Z",
    "updatedAt": "2020-01-10T10:58:41.095Z",
    "related": []
  }
}

media.update

更换媒体或通过媒体界面更新媒体的元数据时会触发此事件。

Example payload

json
{
  "event": "media.update",
  "createdAt": "2020-01-10T10:58:41.115Z",
  "media": {
    "id": 1,
    "name": "image.png",
    "hash": "353fc98a19e44da9acf61d71b11895f9",
    "sha256": "huGUaFJhmcZRHLcxeQNKblh53vtSUXYaB16WSOe0Bdc",
    "ext": ".png",
    "mime": "image/png",
    "size": 228.19,
    "url": "/uploads/353fc98a19e44da9acf61d71b11895f9.png",
    "provider": "local",
    "provider_metadata": null,
    "createdAt": "2020-01-10T10:58:41.095Z",
    "updatedAt": "2020-01-10T10:58:41.095Z",
    "related": []
  }
}

media.delete

仅通过媒体界面删除媒体时才会触发此事件。

Example payload

json
{
  "event": "media.delete",
  "createdAt": "2020-01-10T11:02:46.232Z",
  "media": {
    "id": 11,
    "name": "photo.png",
    "hash": "43761478513a4c47a5fd4a03178cfccb",
    "sha256": "HrpDOKLFoSocilA6B0_icA9XXTSPR9heekt2SsHTZZE",
    "ext": ".png",
    "mime": "image/png",
    "size": 4947.76,
    "url": "/uploads/43761478513a4c47a5fd4a03178cfccb.png",
    "provider": "local",
    "provider_metadata": null,
    "createdAt": "2020-01-07T19:34:32.168Z",
    "updatedAt": "2020-01-07T19:34:32.168Z",
    "related": []
  }
}

review-workflows.updateEntryStage 企业版

此事件仅适用于 Strapi 的 企业版

Example payload

json
{
  "event": "review-workflows.updateEntryStage",
  "createdAt": "2023-06-26T15:46:35.664Z",
  "model": "model",
  "uid": "uid",
  "entity": {
    "id": 2
  },
  "workflow": {
    "id": 1,
    "stages": {
      "from": {
        "id": 1,
        "name": "Stage 1"
      },
      "to": {
        "id": 2,
        "name": "Stage 2"
      }
    }
  }
}

::card{type=tip} Strapi v4.11.4+ 的有效负载格式 review-workflows.updateEntryStage webhook 的有效负载格式在 Strapi v4.11.3 和 Strapi v4.11.4 之间发生了变化。请注意以下示例中的有效负载格式差异，并相应地更新您的集成代码：

Strapi v4.11.3 与 Strapi v4.11.4 的有效负载格式
详情

releases.publish 企业版

当 release 发布时会触发此事件。

Example payload

json

{
  "event": "releases.publish",
  "createdAt": "2024-02-21T16:45:36.877Z",
  "isPublished": true,
  "release": {
    "id": 2,
    "name": "Fall Winter highlights",
    "releasedAt": "2024-02-21T16:45:36.873Z",
    "scheduledAt": null,
    "timezone": null,
    "createdAt": "2024-02-21T15:16:22.555Z",
    "updatedAt": "2024-02-21T16:45:36.875Z",
    "actions": {
      "count": 1
    }
  }
}