--- title: "Webhooks" description: "Learn how to trigger workflows with webhooks in Prismic." category: "concepts" audience: developers lastUpdated: "2026-04-08T22:46:36.000Z" --- A webhook is a message sent by Prismic when a page is published or edited in your repository. The message is delivered as an HTTP `POST` request to a URL of your choosing. > Webhooks can notify your hosting provider to rebuild your website when content changes. See the [instructions](#add-a-webhook-to-your-hosting-provider) below. # Create a webhook Use the [Prismic CLI](https://prismic.io/docs/cli.md) to create a webhook: ```sh npx prismic webhook create https://example.com/my-endpoint ``` You can use the `--trigger` option to determine which [events](#events) trigger the webhook. By default, all events trigger the webhook. ```sh npx prismic webhook create https://example.com/my-endpoint \ --trigger documentsPublished \ --trigger documentsUnpublished ``` See the available commands and options using `--help`: ```sh npx prismic webhook --help ``` You can also manage webhooks in your repository at **Settings** → **Webhooks**. # Events The following events are supported: * A page is published or unpublished. * A release is created, edited, or deleted. * A tag is created or deleted. ## Failed requests are retried If your server responds with anything other than a `200` response, the delivery will be re-attempted every 10 minutes up to 5 times. > **Important** > > Prismic will automatically disable a webhook if it fails five times consecutively. ## Recent triggers are logged You will find a list of the most recent triggers on your repository's **Webhooks** page. Click **See the logs** on a specific webhook or click the **Logs** tab to see all events from the past 30 days. # Add a webhook to your hosting provider Follow these steps to notify your hosting provider to rebuild your website when content changes. * **Netlify:** 1. **Open your Netlify project settings** Navigate to your Netlify project and go to **Site configuration** > **Continuous deployment**. 2. **Create a build hook** In the **Build hooks** section, click **Add build hook** and use the following values: | Field | Value | | ------------------- | ------------------------------------- | | **Build hook name** | "Prismic" | | **Branch to build** | Select the Git branch name to deploy. | Click **Save**. 3. **Use the webhook URL** Create the webhook using the [Prismic CLI](https://prismic.io/docs/cli.md) as described in [Create a webhook](#create-a-webhook). ```sh # Replace [your-url] with your build hook URL npx prismic webhook create [your-url] \ --trigger documentsPublished \ --trigger documentsUnpublished ``` * **Vercel:** 1. **Open your Vercel project settings** Navigate to your Vercel project and go to **Settings** > **Git**. 2. **Create a build hook** In the **Deploy Hooks** section, fill out the **Create Hook** form with the following values: | Field | Value | | ---------- | ------------------------------ | | **Name** | "Prismic" | | **Branch** | The Git branch name to deploy. | Click **Create Hook**. 3. **Use the webhook URL** Create the webhook using the [Prismic CLI](https://prismic.io/docs/cli.md) as described in [Create a webhook](#create-a-webhook). ```sh # Replace [your-url] with your build hook URL npx prismic webhook create [your-url] \ --trigger documentsPublished \ --trigger documentsUnpublished ``` * **AWS Amplify:** 1. **Open your AWS Amplify project settings** Navigate to your AWS Amplify project and go to **App settings** > **Build settings**. 2. **Create a build hook** In the **Incoming webhooks** section, click **Create webhook** and use the following values: | Field | Value | | ---------- | ------------------------------------- | | **Name** | "Prismic" | | **Branch** | Select the Git branch name to deploy. | Click **Save**. 3. **Use the webhook URL** Create the webhook using the [Prismic CLI](https://prismic.io/docs/cli.md) as described in [Create a webhook](#create-a-webhook). ```sh # Replace [your-url] with your build hook URL npx prismic webhook create [your-url] \ --trigger documentsPublished \ --trigger documentsUnpublished ``` # Payload Webhook payloads include the following properties. | Property | Type | Description | Default | | ----------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | type | "api-update" \| "test-trigger" | Type of the webhook. | None | | secret (optional) | string \| null | The configured secret, if there is one. | `null` | | masterRef | string | The new master ref. | None | | domain | string | Your Prismic repository name. | None | | apiUrl | string | Your Prismic repository URL. | None | | releases | object | A list of changes made to releases. | None | | releases.addition | object\[] | List of added releases. Each object contains the `id`, `ref`, and `label` of the added releases as well as an array with the IDs of the pages added to the release. | None | | releases.update | object\[] | List of updated releases. Each object contains the `id`, `ref`, `label`, and `scheduledAt` of the updated releases as well as an array with the IDs of the pages added to the release. | None | | releases.deletion | object\[] | List of deleted releases. Each object contains the `id`, `ref`, and `label` of the deleted releases as well as an array with the IDs of the pages added to the release. | None | | tags | object | A list of changes made to tags. | None | | tags.addition | object\[] | List of changes made to tags. Each object contains the `id` of the added tags. | None | | tags.deletion | object\[] | List of changes made to tags. Each object contains the `id` of the deleted tags. | None | | documents | string\[] | A list of page IDs that changed. | None | | bookmarks (deprecated) | object | Legacy field. Do not use. | None | | collection (deprecated) | object | Legacy field. Do not use. | None | # Example payloads Seven events can trigger a webhook call. See the examples of each of the webhook triggers. ## A page is published The published page ID gets added to the `documents` array. ```json {8} { "type": "api-update", "masterRef": "X6qn-RIAACMAVge1", "releases": {}, "masks": {}, "tags": {}, "experiments": {}, "documents": ["X6LcjhAAAB8AUJwb"], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` ## A page is unpublished The unpublished page ID gets added to the `documents` array. ```json {8} { "type": "api-update", "masterRef": "X66c6xIAACEAZ8LK", "releases": {}, "masks": {}, "tags": {}, "experiments": {}, "documents": ["X3b_1hIAACMA-YWk"], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` > **Important** > > The payload for a webhook triggered when a page is *published* looks identical to when a page is *unpublished*. You might need to configure two separate endpoints to handle these two scenarios. ## A release is created The metadata of the created release gets added to the `releases.addition` array. ```json {3-14} { "type": "api-update", "releases": { "addition": [ { "id": "X66oBhIAACMAaDeo", "ref": "X66oBhIAABMAaDep~X66c6xIAACEAZ8LK", "label": "release4", "documents": [ "X3Lb_VGRfEAUJlg", ] } ] }, "masks": {}, "tags": {}, "experiments": {}, "documents": [], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } } ``` > **Important** > > When you create a release from inside a page, you get an `update` event instead of an `addition` event. This happens because you add the new release and immediately update it by adding a page to it. ## A release is updated When you modify the publication date, the metadata of the updated release gets added to the `releases.update` array. ```json {3-13} { "type": "api-update", "releases": { "update": [ { "id": "X5G-wBIAACYAfrlX", "ref": "X5G-zxIAABIAfrmd~X6qyuRIAACIAVjA7", "label": "webhookstest", "scheduledAt": 1605135600000, "documents": ["X6Lb_xAAAFTVUJlg"] } ] }, "masks": {}, "tags": {}, "experiments": {}, "documents": [], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` > The release's `ref` value gets updated each time you add a new page or edit and save any page already in the release. ## A release is deleted When you delete a release, the metadata of the deleted release gets added to the `releases.deletion` array. ```json {4-14} { "type": "api-update", "masterRef": "XaBPIxEAABkAe5n8", "releases": { "deletion": [ { "id": "XZ9MwBEAABkAdylL", "ref": "XZ9NKBEAAA8Adysd~XaBN7BEAABkAe5Sg", "label": "test", "scheduledAt": 1572523200000, "documents": ["X6Lb_xAAACEAUJlg"] } ] }, "bookmarks": {}, "masks": {}, "collection": {}, "tags": {}, "experiments": {}, "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` > **Important** > > A published release also triggers a "Release is deleted" Webhook. ## A new tag is added to your Prismic repository When you publish a page that uses a new tag, it gets added to the `tags.addition` array and the ID of the published page gets added to the `documents` array. That this webhook will only trigger a page published with a new tag the first time. If another page is published with this same tag, the webhook will not be triggered. ```json {6-12} { "type": "api-update", "masterRef": "X6A5sxIAACkAvjzh", "releases": {}, "masks": {}, "tags": { "addition": [ { "id": "testtag" } ] }, "experiments": {}, "documents": ["XxhMhBMAACAAWMp6"], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` ## A tag is deleted from your Prismic repository This trigger occurs when you delete a tag from your repository. This is done when you remove the tag from all the pages that use it. The tag gets added to the `tags.deletion` array and the ID of the published page gets added to the `documents` array. ```json {6-12} { "type": "api-update", "masterRef": "X6A8CRIAACcAvkbK", "releases": {}, "masks": {}, "tags": { "deletion": [ { "id": "old blogs" } ] }, "experiments": {}, "documents": ["XxhMhBMAACAAWMp6"], "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ``` ## A test trigger A test trigger is sent when clicking the **Trigger it** button in your repository's webhook settings. ```json {2} { "type": "test-trigger", "domain": "your-repo-name", "apiUrl": "https://your-repo-name.prismic.io/api", "secret": null } ```