Skip to main content

网络钩子

¥Webhooks

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

¥Webhook is a construct used by an application to notify other applications that an event occurred. More precisely, webhook is a user-defined HTTP callback. Using a webhook is a good way to tell third party providers to start some processing (CI, build, deployment ...).

Webhook 的工作方式是通过 HTTP 请求（通常是 POST 请求）向接收应用传递信息。

¥The way a webhook works is by delivering information to a receiving application through HTTP requests (typically POST requests).

用户内容类型 webhook​

¥User content-type webhooks

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

¥To prevent from unintentionally sending any user's information to other applications, Webhooks will not work for the User content-type. If you need to notify other applications about changes in the Users collection, you can do so by creating Lifecycle hooks using the ./src/index.js example.

可用配置​

¥Available configurations

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

¥You can set webhook configurations inside the file ./config/server.

  • webhooks

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

      ¥defaultHeaders: You can set default headers to use for your webhook requests. This option is overwritten by the headers set in the webhook itself.

配置示例

¥Example configuration

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

保护你的网络钩子​

¥Securing your webhooks

大多数时候，Webhook 会向公共 URL 发出请求，因此有人可能会找到该 URL 并向其发送错误信息。

¥Most of the time, webhooks make requests to public URLs, therefore it is possible that someone may find that URL and send it wrong information.

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

¥To prevent this from happening you can send a header with an authentication token. Using the Admin panel you would have to do it for every webhook. Another way is to define defaultHeaders to add to every webhook requests.

你可以通过更新 ./config/server 处的文件来配置这些全局标头：

¥You can configure these global headers by updating the file at ./config/server:

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

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

¥If you are developing the webhook handler yourself you can now verify the token by reading the headers.

可用的事件​

¥Available events

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

¥By default Strapi webhooks can be triggered by the following events:

名称描述
entry.create创建内容类型条目时触发。
entry.update更新内容类型条目时触发。
entry.delete删除内容类型条目时触发。
entry.publish发布内容类型条目时触发。*
entry.unpublish当内容类型条目取消发布时触发。*
media.create创建媒体时触发。
media.update当媒体更新时触发。
media.delete删除媒体时触发。
review-workflows.updateEntryStage当内容在审阅阶段之间移动时触发（请参阅 审查工作流程）。
此事件仅适用于 Enterprise 版本的 Strapi。
releases.publish发布版本时触发（请参阅 发布）。
此事件仅适用于 Strapi 的 Enterprise 版本和 Strapi Cloud 的 Strapi Cloud Team 计划。

*仅当在此内容类型上启用 draftAndPublish 时。

¥*only when draftAndPublish is enabled on this Content Type.

有效载荷​

¥Payloads

💡 注意

打印当前安装的 Strapi 版本。

¥Private fields and s are not sent in the payload.

标头​

¥Headers

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

¥When a payload is delivered to your webhook's URL, it will contain specific headers:

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

entry.create​

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

¥This event is triggered when a new entry is created.

有效负载示例

¥Example payload

{
  "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​

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

¥This event is triggered when an entry is updated.

有效负载示例

¥Example payload

{
  "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​

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

¥This event is triggered when an entry is deleted.

有效负载示例

¥Example payload

{
  "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​

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

¥This event is triggered when an entry is published.

有效负载示例

¥Example payload

{
  "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​

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

¥This event is triggered when an entry is unpublished.

有效负载示例

¥Example payload

{
  "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​

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

¥This event is triggered when you upload a file on entry creation or through the media interface.

有效负载示例

¥Example payload

{
  "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​

当你通过媒体接口更换媒体或更新媒体元数据时，会触发该事件。

¥This event is triggered when you replace a media or update the metadata of a media through the media interface.

有效负载示例

¥Example payload

{
  "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​

仅当你通过媒体接口删除媒体时才会触发该事件。

¥This event is triggered only when you delete a media through the media interface.

有效负载示例

¥Example payload

{
  "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 <企业徽章/>​

¥review-workflows.updateEntryStage Enterprise

此事件仅适用于 Enterprise 版本的 Strapi。
当内容移至新的审核阶段时（请参阅 审查工作流程），将触发该事件。

¥This event is only available with the Enterprise edition of Strapi.
The event is triggered when content is moved to a new review stage (see Review Workflows).

有效负载示例

¥Example payload

{
  "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"
      }
    }
  }
}

releases.publish <企业徽章/><云团队徽章/>​

¥releases.publish EnterpriseStrapi Cloud Team

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

¥The event is triggered when a release is published.

有效负载示例

¥Example payload


{
  "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
    }
  }
}