Webhooks

A webhook is a simple message sent by Prismic when a document is published or edited in your repository. The message is delivered as an HTTP request to a URL of your choosing. You can use webhooks to tell your hosting provider to rebuild your web app when the content has changed.

Create a webhook

In your repository, go to** **Settings > Webhooks. You must be the repository owner or have admin rights.

In the configuration, enter a Name_ for your webhook, a Webhook URL,_ and an optional Secret that will function as a “password” in your webhook request.

If you add a secret, Prismic will include it in the webhook so that you can verify that the request is coming from Prismic.

Select the triggers you need for your webhook. Read the details about each one in the Webhook triggers section below.

Once your webhook is added, click Trigger it_ _to check if it’s working. You can also run a test with your webhooks in a service like RequestBin.com.

If your server responds with anything other than a 200 response, the delivery will be re-attempted every 10 minutes up to 5 times.

You will find a list of the most recent triggers on the Webhooks page. Click See the logs or in the Logs tab to see the event details from the past 30 days.

Add a webhook to your hosting provider

Netlify

In your Netlify project, go to Site settings > Build & deploy > Continuous Deployment > Build hooks. Click Add a build hook. Enter a name (e.g. “Prismic”) and choose the branch of your git repository to deploy, then click Save.

Copy the URL and enter it in the Webhook URL field of your webhook settings in Prismic, as described above.

Vercel

In your Vercel project, go to Settings > Git > Deploy Hooks. Enter a name (e.g. “Prismic”) and type in the name of the branch of the git repository to deploy, then click Create Hook.

Copy the URL and enter it in the Webhook URL field of your webhook settings in Prismic, as described above.

Amplify

In your Amplify app, go to Build Settings, and click Create webhook. Enter a name (e.g. “Prismic”) and select the branch of the git repository to deploy, then click Save.

Copy the URL and enter it in the Webhook URL field of your webhook settings in Prismic, as described above.

Set custom headers

Prismic webhooks allow you to set the header of the webhook payload. This is useful, for example, if you’re using Github Actions that require a personal access token. To learn more, refer to the Github docs.

To do so, add the header key and value, as shown below.

Payload

The following table displays all the possible fields delivered in the payload of a webhook. This varies depending on the trigger.

The documents array is a list of IDs of documents that have changed. This data can be valuable in frameworks that support incremental builds.

Here is an example of a webhook payload that includes every possible field that could be retrieved depending on the trigger:

{
  "type": "api-update",
  "secret": "mys3cr8t!!",
  "masterRef": "U_tMgS8AADQA1t37",
  "domain": "your-repo-name",
  "apiUrl": "https://your-repo-name.prismic.io/api",
  "releases": {
    "addition": [
      {
        "id": "U_sstwlGABFGWvul",
        "ref": "U_sstwlGAAxGWvum",
        "label": "A new release",
        "documents": ["XDF-DhEAACAA5b4F"]
      }
    ],
    "update": [
      {
        "id": "U_ss111GABFGWvul",
        "ref": "U_sstwlG222GWvum",
        "label": "Some existing release",
        "documents": ["XDF-DhEAACAA5b4F"]
      }
    ],
    "deletion": [
      {
        "id": "U_sstwlGAB333vul",
        "ref": "U_sstwlGAAxG555m",
        "label": "A not-so-important release",
        "documents": ["XDF-DhEAACAA5b4F"]
      }
    ]
  },
  "bookmarks": {},
  "collection": {},
  "tags": {
    "addition": [
      {
        "id": "current news"
      }
    ],
    "deletion": [
      {
        "id": "past news"
      }
    ]
  },
  "documents": ["X3b_fxIAACAA-YQY"]
}

Triggers

Seven events can trigger a webhook call. See the examples of each of the webhook triggers.

A document is published

The published document ID gets added to the documents array.

{
  "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 document is unpublished

The unpublished document ID gets added to the documents array.

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

A release is created

The metadata of the created release gets added to the releases.addition array.

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

A release is updated

When you modify the publication date, the metadata of the updated release gets added to the releases.update array.

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

A release is deleted

When you delete a release, the metadata of the deleted release gets added to the releases.deletion array.

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

A new tag is added to your Prismic repository

When you publish a document that uses a new tag, it gets added to the tags.addition array and the ID of the published document gets added to the documents array.

That this webhook will only trigger a document published with a new tag the first time. If another document is published with this same tag, the webhook will not be triggered.

{
  "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 documents that use it. The tag gets added to the tags.deletion array and the ID of the published document gets added to the documents array.

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