Webhooks
Learn how to trigger workflows with webhooks in Prismic.
A webhook is a message sent by Prismic when a document is published or edited in your repository. The message is delivered as an HTTP POST
request to a URL of your choosing.
Events
The following events are supported:
- A document is published or unpublished.
- A release is created, edited, or deleted.
- A tag is created or deleted.
Failed requests are retried
If your server responds with anything other than a 200
response, the delivery will be re-attempted every 10 minutes up to 5 times.
Recent triggers are logged
You will find a list of the most recent triggers on your repository’s Webhooks page.
Click See the logs on a specific webhook or click the Logs tab to see all events from the past 30 days.
Create a webhook
Follow these steps to create a webhook for your Prismic repository.
Open your repository settings
Navigate to your Prismic repository and go to Settings > Webhooks.
You must be the repository owner or have admin rights to access the Webhooks page.
Set up the webhook
Click the Create a webhook button. If you don’t have any webhooks already set up, you won’t see the button and instead will already see a form.
Fill out the form with a name and the URL you would like the webhook to request.
If you add a secret, Prismic will include it in the webhook so you can verify that the request came from Prismic.
(Optional) Add custom headers
You can add headers from the webhook configuration form. Adding headers is useful if, for example, you’re using Github Actions that require a personal access token.
(Optional) Customize triggers
By default, the webhook will be triggered in response to the following events:
- A document is published or unpublished.
- A release is created, edited, or deleted.
- A tag is created or deleted.
You can disable any of these events from triggering the webhook by unchecking the trigger.
Create and test your webhook
Click the Add this webhook button to finalize your webhook.
After creating the webhook, click the Trigger it button to send a test request to your webhook.
Add a webhook to your hosting provider
Follow these steps to notify your hosting provider to rebuild your website when content changes.
Open your Netlify project settings
Navigate to your Netlify project and go to Site configuration > Continuous deployment.
Create a build hook
In the Build hooks section, click Add build hook and use the following values:
Field Value Build hook name ”Prismic” Branch to build Select the Git branch name to deploy. Click Save.
Use the webhook URL
Copy the URL and enter it in the webhook URL field of your Prismic webhook settings, as described in Create a webhook.
Payload
Webhook payloads include the following properties.
type
"api-update" | "test-trigger"
secret
string | null
The configured secret, if there is one.
null
masterRef
string
domain
string
apiUrl
string
releases
object
A list of changes made to releases.
releases.addition
object[]
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
object[]
List of updated releases. Each object contains the id
, ref
, label
,
and scheduledAt
of the updated releases as well as an array with the IDs
of the documents added to the release.
releases.deletion
object[]
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.
tags
object
tags.addition
object[]
List of changes made to tags. Each object contains the id
of the added
tags.
tags.deletion
object[]
List of changes made to tags. Each object contains the id
of the deleted
tags.
documents
string[]
A list of document IDs that changed.
bookmarks
object
collection
object
Example payloads
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.
{
"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.
{
"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
}
A release is created
The metadata of the created release gets added to the releases.addition
array.
{
"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
}
}
A release is updated
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
}
A release is deleted
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
}
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.
{
"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.
{
"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
}
A test trigger
A test trigger is sent when clicking the Trigger it button in your repository’s webhook settings.
{
"type": "test-trigger",
"domain": "your-repo-name",
"apiUrl": "https://your-repo-name.prismic.io/api",
"secret": null
}