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.
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.
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.
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.
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.
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
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"
],
}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.