Webhooks

Learn how to trigger workflows with Webhooks in Prismic

Webhooks are events that are triggered when certain actions are performed in your Prismic repository. The most common action is when a document is published or edited.

How do they work, and what can I do with them?

There are many things that you can do when your content changes. You may want to trigger a build or deployment for your website or application, notify your team of edits made to the documents in a release, or other changes happening in your repository.

Disabled webhooks

Prismic will automatically disable a webhook if it fails five times consecutively.

Configure Webhooks

Add a new 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 triggers

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

Test your Webhook

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 attempted every 10 minutes up to 5 times.

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

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.

Screenshot of a Webhook custom headers configuration

The Webhook payload

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

type

string

Name of the Webhook

secret

string

The configured secret, if there is any

masterRef

string

The new master ref

domain

string

Your repository name

apiUrl

string

Your repository URL

releases

object

List of changes made to Releases

releases.addition

array

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 documents added to the release.

releases.update

array

List of updated Releases. Each object contains the "id", "ref", "label" and "scheduledAt' which is the time of the scheduled time of the updated release; as well as an array with the IDs of the documents added to the release.

releases.deletion

array

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 documents added to the release.

bookmarks

object

Legacy field

collection

object

Legacy field

Determining which documents have changed

The Webhook payload includes the documents array that provides the list of document IDs that have changed:

Copy

"documents": ["X3b_fxIAACAA-YQY", "N4b_fxIAACAA-YQY"]

This data can be useful for various use cases, such as frameworks that support incremental builds.

Webhook 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.

Copy

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

Copy

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

Published vs. unpublished

The payload for a Webhook triggered when a document is published looks identical to when a document 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.

Copy

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

Update vs. addition

When you create a Release from inside a document, you get an update event instead of an addition event, because you add the new Release and immediately update it by adding a document 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.

Copy

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

The Releases ref value gets updated each time you add a new document or edit and save any document 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.

Copy

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

Published vs. deleted

A published Release also triggers A release is deleted Webhook.

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.

Copy

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

Copy

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

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.