Webhooks

Learn how to trigger workflows with webhooks in Prismic


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.

Disabled webhooks

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

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.

Screenshot of an active webhook

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

Screenshot of Netlify's build hooks setting.

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

Screenshot of Vercel's deploy hooks setting.

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

Screenshot of Amplify's Incoming webhooks setting.

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.

Screenshot of a webhook custom headers configuration

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

tags 

object

List of changes made to Tags

tags.addition 

array

List of changes made to tags. Each object contains the "id" of the added tags.

tags.deletion 

array

List of changes made to tags. Each object contains the "id" of the deleted tags.

documents 

array

List of documents that changed in the main api

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:

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

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.