Webhooks

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.

Payload

Webhook payloads include the following properties.

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
}