What is a webhook?

A webhook is an event that is triggered whenever a change is published on your Prismic repository. The webhook will send a POST request to your website server, which can signal it to perform a certain action. For example: regenerating a static website, sending a newsletter, updating a cache, etc.

You just need to build a URL on your server that will trigger the action. You can then set up a webhook in your repository settings that will call this URL when any new change is published.

Webhook triggers

There are a number of events that will trigger a webhook.

  • A new document is published
  • An existing document is edited and re-published
  • A document is archived
  • A release is created, edited, or deleted
  • A tag is created, edited, or deleted
  • A bookmark is created, edited, or deleted
  • A collection is created, edited, or deleted

Body of the webhook

The body of a webhook POST request is a JSON object containing data about the event that triggered the webhook.

Here is an example of a webhook body that includes every possible field that could be encountered.

{
  "type": "api-update",
  "secret": "mys3cr8t!!",           // the configured secret, if any
  "masterRef" : "U_tMgS8AADQA1t37", // the new ref of the master
  "domain": "lesbonneschoses",      // your repository domain
  "apiUrl": "https://lesbonneschoses.prismic.io/api",
  "releases": {                   // --- CHANGES TO RELEASES
    "addition": [{                // releases that were just added
      "id": "U_sstwlGABFGWvul",
      "ref": "U_sstwlGAAxGWvum",
      "label": "A new release"
    }],
    "update": [{                  // releases that were updated
      "id": "U_ss111GABFGWvul",
      "ref": "U_sstwlG222GWvum",  // this is the new, updated ref of the release
      "label": "Some existing release"
    }],
    "deletion": [{                // deleted releases
      "id": "U_sstwlGAB333vul",
      "ref": "U_sstwlGAAxG555m",
      "label": "A not-so-important release"
    }]
  },
  "bookmarks" : {                 // --- CHANGES TO BOOKMARKS
    "addition" : [],              // bookmarks that were just added
    "update" : [ {                // bookmarks that were updated
      "id" : "wr-tour",
      "docId" : "Ux-CMgEAAFwI9kFg"
    } ],
    "deletion": []                // deleted bookmarks
  },
  "collection": {                 // --- CHANGES TO COLLECTIONS
    "addition": [ {               // collections that were just added
      "id": "U_sstwlGABFGWvul",
      "label": "A new collection"
    } ],
    "update": [],                 // collections that were updated
    "deletion": []                // deleted collections
  },
  "tags": {                       // --- CHANGES TO TAGS
    "addition": [ {               // tags that were just added
      "id": "scala"
    } ],
    "update": [],                 // tags that were updated
    "deletion": [ {               // deleted tags
      "id": "java"
    } ]
  }
}


Note that the above JSON example demonstrates all possible changes. The request body will usually be much smaller because it only contains the changes that triggered the webhook.

It is worth noting that the Webhook response does not specify what has changed, just that something has changed.
 

Determining which documents have changed

There are a couple of tricks you can use to determine what documents have been added or updated. 

After you receive a webhook you could do a query based on the Last Publication Date to see which documents have been changed or added recently. Note that this won't tell you if anything has been archived or deleted.

Another option is to keep a snapshot of your content. When you receive a webhook, query all your content and compare this to your snapshot to see what changed.
 

Configuring your webhook URL

Go to Settings / Webhooks. 

Here you can create a new webhook. You will need to enter the webhook URL and a Secret. The secret is an optional "password" that will be added to your webhook request. 

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, then start the webhook action.
 

Test your webhook

You can test your webhooks with a service like requestb.in

You can trigger and test your webhook any time! Just click on the "Trigger it" button.

In case your server responds with anything else than a 2xx 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 Webhook settings page. 

Did this answer your question?