Please note that with Webhooks, you need to be careful with updating a cache or regenerating a static page build. You need to keep in mind that a document that is updated might affect the content on another page because of Content Relationships.

What are they?

Webhooks are events that are triggered when certain actions are done in your Prismic repository. A typical example of this is when content is published, and the API is updated.

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 rebuild your website or application, notify your team, send a post or tweet, or re-sync your website cache.

Configuring your Webhook URL

To activate Webhooks for your repository:

  • Go to Settings / Webhooks. You need to be the repository owner or have admin rights to access it.
  • Create a new Webhook. You will need to enter the Webhook URL (must be reachable from the Internet) and optionally a Secret that will function as a "password" that will be added to your Webhook request. If you do this, Prismic will send the content to your server so that you can verify that the request is coming from prismic.io.

Since your URL needs to be accessible online for the Prismic Webhook to reach it, it is recommended that you configure your code so that it first makes sure that the secret password is correct. If it is correct, you can then start the Webhook action.

Select the corresponding type of triggers that you need.

Test your Webhook

Once your Webhook is added, you can trigger and test it at any time! Just click on the "Trigger it" button.

In case your server responds with anything other than a 2xx response, the delivery will be attempted every 10 minutes (up to 5 times).

You can test your Webhooks with a service like RequestBin.com.

Webhooks can still be fired off for the creation of releases regardless of other settings, but you can now configure other triggers to cause the publication to fire. You could configure specific URLs that deal with each one.

We've mentioned a few possible usages of Webhooks, but the only limit is your imagination! If you find a neat application for them or create a service integration, let us know. We love getting feedback and interesting use-cases!

Managing existing Webhooks

You will find a list of the most recent triggers on the Webhooks page. Click the 'See the logs' link or the 'Logs' tab.

You'll be able to see the event details from the past 30 days.

Custom headers

There are some use-cases where an application requires some fields to be added in the header of the Webhook payload, such as Github, Gitlab, CircleCI, etc...

For example, building or using Github Actions require users to add a personal access token with the repo scope key. To learn more, refer to Github's docs.

All you need to do is add the header key & value, as shown below.

The Webhook payload

Here is an example of a Webhook body that includes every possible field that could be encountered depending on the trigger:

{
"type": "api-update",
"secret": "mys3cr8t!!", // The configured secret, if any
"masterRef" : "U_tMgS8AADQA1t37", // The new master ref
"domain": "your-repo-name", // Your repository name
"apiUrl": "https://your-repo-name.prismic.io/api",
"releases": { // --- CHANGES TO RELEASES
"addition": [{ // Releases that were added
"id": "U_sstwlGABFGWvul",
"ref": "U_sstwlGAAxGWvum",
"label": "A new release",
"documents": [ // Documents that were added to the release
"XDF-DhEAACAA5b4F"
]
}],
"update": [{ // Releases that were updated
"id": "U_ss111GABFGWvul",
"ref": "U_sstwlG222GWvum", // Updated release ref
"label": "Some existing release",
"documents": [ // Documents that changed
"XDF-DhEAACAA5b4F"
]
}],
"deletion": [{ // Deleted releases
"id": "U_sstwlGAB333vul",
"ref": "U_sstwlGAAxG555m",
"label": "A not-so-important release",
"documents": [ // Documents that were deleted
"XDF-DhEAACAA5b4F"
]
}]
},
"bookmarks" : {}, // --- Legacy field
"collection": {}, // --- Legacy field
"tags": { // --- CHANGES TO TAGS
"addition": [ { // Tags that were added
"id": "scala"
} ],
"update": [], // tags that were updated.
"deletion": [ { // Deleted tags.
"id": "java"
} ]
},
"documents": [
"X3b_fxIAACAA-YQY" // Documents that changed in the main api
],
}

What can trigger a Webhook

There are 6 events that can trigger a Webhook call.

A document is published

The published document id gets added to the documents fields when this event gets triggered, as shown below.

{
"type": "api-update",
"masterRef": "X6qn-RIAACMAVge1",
"releases": {},
"masks": {},
"tags": {},
"experiments": {},
"documents": [
"X6LcjhAAAB8AUJwb" // The published docucment
],
"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 fields when this event gets triggered, as shown below.

{
"type": "api-update",
"masterRef": "X66c6xIAACEAZ8LK",
"releases": {},
"masks": {},
"tags": {},
"experiments": {},
"documents": [
"X3b_1hIAACMA-YWk" // The unpublished document
],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

You might notice that the payload for a Webhook triggered when a document is published looks identical to that of a document being unpublished. This means that you might need to configure two separate endpoints to handle these two scenarios.

A release is created

A Webhook can be triggered when a new Release is created. The example Webhook payload below shows the release details along with the documents included in the release.

{
"type": "api-update",
"releases": {
"addition": [ // The new release creation event
{
"id": "X66oBhIAACMAaDeo", // The new release id
"ref": "X66oBhIAABMAaDep~X66c6xIAACEAZ8LK", // The new release ref
"label": "release4",
"documents": []
}
]
},
"masks": {},
"tags": {},
"experiments": {},
"documents": [],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}
}

Note that when you create a release from inside a document, you get an update event inside the release instead of an addition event, as shown in the following example. This is because you technically add the new Release and immediately update it by adding a document to it.

{
"type": "api-update",
"releases": {
"update": [ // Here it shows update rather than addition
{
"id": "X6qq1BIAACEAVg1H", // The new release id
"ref": "X6qq1BIAACUAVg1J~X6qqwBIAACEAVg0i", // The new release ref
"label": "release2", // The new release label
"documents": [
"X6LcRBAAACIAUJqp" // The documents included in the release
]
}
]
},
"masks": {},
"tags": {},
"experiments": {},
"documents": [],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

A release is edited or deleted

When a Webhook is triggered by a Release being edited or deleted, the Webhook payloads shows the release details along with the documents included in the release.

{
"type": "api-update",
"releases": {
"update": [
{
"id": "X5G-wBIAACYAfrlX",
"ref": "X5G-zxIAABIAfrmd~X6qyuRIAACIAVjA7",
"label": "webhookstest",
"scheduledAt": 1605135600000, // The updated scheduled date
"documents": []
}
]
},
"masks": {},
"tags": {},
"experiments": {},
"documents": [],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

Here is an example of Webhook payload when a Release is deleted.

{
"type": "api-update",
"masterRef": "XaBPIxEAABkAe5n8",
"releases": {
"deletion": [ // The deleted release
{
"id": "XZ9MwBEAABkAdylL",
"ref": "XZ9NKBEAAA8Adysd~XaBN7BEAABkAe5Sg",
"label": "test",
"scheduledAt": 1572523200000,
"documents": [ // The documents included in this release
"X6Lb_xAAACEAUJlg",
"X6LcRBAAACIAUJqp"
]
}
]
},
"bookmarks": {},
"masks": {},
"collection": {},
"tags": {},
"experiments": {},
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

Note that when a Release gets published, it will also trigger a "Document is published" Webhook. It will result in the Webhook payload shown below.

Publishing a Release adds an item in the deletion array field (because the Release is deleted after it is published). It will also show you the documents contained in this Release. Those documents should also match what is in the documents field at the bottom of the payload because those documents are being published.

{ 
"type": "api-update",
"masterRef": "X5BeBhAAACMAUaLE", // The new master ref
"releases": {
"deletion": [ // The published release
{
"id": "X47-hhAAACEAS5RD",
"ref": "X5Bd1RAAABAAUaHd~X5BdyhAAACIAUaGs",
"label": "release name",
"documents": [
"X3b_6xIAACEA-YYE",
"X47-ThAAACAAS5NV"
]
}
]
},
"masks": {},
"tags": {},
"experiments": {},
"documents": [ // The published documents
"X3b_6xIAACEA-YYE",
"X47-ThAAACAAS5NV"
],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

Note that the Releases ref field value gets updated each time you add a new document or edit and save any document already in the Release.

{
"type": "api-update",
"masterRef": "XaBLZREAABkAe4l-",
"releases": {
"update": [
{
"id": "XZ9MwBEAABkAdylL",
"ref": "XZ9NKBEAAA8Adysd~XaBLZREAABkAe4l-", // The new ref
"label": "test",
"scheduledAt": 1572001200000,
"documents": [
"XDF-DhEAACAA5b4F"
]
}
]
},
"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

A Webhook can be triggered when you add a new tag to your repo. This is done when you publish a document that uses a brand new tag.

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

Here you can see an example Webhook payload. In the tags field, you'll see additions which will list all the new tags. The documents field will show the document(s) that were published.

{
"type": "api-update",
"masterRef": "X6A5sxIAACkAvjzh",
"releases": {},
"masks": {},
"tags": {
"addition": [
{
"id": "testtag" // The created tag
}
]
},
"experiments": {},
"documents": [
"XxhMhBMAACAAWMp6" // The related published document
],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

A tag is deleted from your Prismic repository

A Webhook can be triggered when you delete a tag from your repo. This is done when you remove and publish all the documents that use that tag.

Here you can see an example Webhook payload. In the tags field, you'll see deletion which will list all the removed tags. The documents field will show the document(s) that were published to trigger the Webhook.

{
"type": "api-update",
"masterRef": "X6A8CRIAACcAvkbK",
"releases": {},
"masks": {},
"tags": {
"deletion": [
{
"id": "testtag" // The deleted tag
}
]
},
"experiments": {},
"documents": [
"XxhMhBMAACAAWMp6" // The related published document
],
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}

Determining which documents have changed

The Webhook payload includes a field at the root level of the JSON called documents that provide the list of documents that have changed, as seen below.

"documents": [
"X3b_fxIAACAA-YQY"
]

This data can be useful for many use cases, such as frameworks that support incremental builds. Once again, you need to keep in mind that a document that is updated might affect the content on another page because of Content Relationships. Updating the cache or static build for only that page given in the Webhook might not be enough.

Did this answer your question?