网络钩子

¥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

JavaScript
TypeScript

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

./config/server.ts
export default {
  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:

Simple token
Environment variable

JavaScript
TypeScript

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

./config.server.ts
export default {
  webhooks: {
    defaultHeaders: {
      Authorization: "Bearer my-very-secured-token",
    },
  },
};

JavaScript
TypeScript

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

./config/server.ts
export default {
  webhooks: {
    defaultHeaders: {
      Authorization: `Bearer ${process.env.WEBHOOK_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

💡 注意

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

¥Private fields and passwords 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"
      }
    }
  }
}

✋ Strapi v4.11.4+ 的有效负载格式

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

¥The payload format for the review-workflows.updateEntryStage webhook changed between Strapi v4.11.3 and Strapi v4.11.4. Please notice the payload format differences in the following examples and update your integration code accordingly:

Payload formats for Strapi v4.11.3 vs. Strapi v4.11.4

在 Strapi v4.11.3 中，webhook 负载具有以下结构：

¥In Strapi v4.11.3 the webhook payload has the following structure:

{
  "event": "review-workflows.updateEntryStage",
  "createdAt": "2023-06-30T11:40:00.658Z",
  "model": "model",
  "uid": "uid",
  "entry": {
    "entityId": 2,
    "workflow": {
      "id": 1,
      "stages": {
        "from": 1,
        "to": 2
      }
    }
  }
}

在 Strapi v4.11.4 中，webhook 有效负载具有以下结构：

¥In Strapi v4.11.4 the webhook payload has the following structure:

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

网络钩子

用户内容类型 webhook​

可用配置​

保护你的网络钩子​

可用的事件​

有效载荷​

标头​

entry.create​

entry.update​

entry.delete​

entry.publish​

entry.unpublish​

media.create​

media.update​

media.delete​

review-workflows.updateEntryStage <企业徽章/>​

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

用户内容类型 webhook

可用配置

保护你的网络钩子

可用的事件

有效载荷

标头

`entry.create`

`entry.update`

`entry.delete`

`entry.publish`

`entry.unpublish`

`media.create`

`media.update`

`media.delete`

`review-workflows.updateEntryStage` <企业徽章/>

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