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.
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.
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 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.
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.
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
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"
],
}
The Webhook payload includes the documents array that provides the list of document IDs that have changed:
"documents": ["X3b_fxIAACAA-YQY", "N4b_fxIAACAA-YQY"]
This data can be useful for various use cases, such as frameworks that support incremental builds.
Seven events can trigger a Webhook call. See the examples of each of the Webhook triggers.
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
}
{
"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.
{
"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.
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
}
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.
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
}
Published vs. deleted
A published Release also triggers A release is deleted Webhook.
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
}
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
}
Was this article helpful?
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.