Finer grain control with Prismic webhooks

The day that you have all been waiting for has finally arrived - we're giving you more control over your webhooks! Go on, go to your settings and spend the afternoon playing around with your configurations, there's no one here to stop you.

Want the full details? Just read on.

What are they?

Webhooks are events that are triggered whenever a change is published on your Prismic repository and the API is updated. Up until now, you have had little control over what triggers your webhooks and we have been sending you webhooks for a wide range of events - potentially causing your website to rebuild even though you were just creating a new release in your Writing Room. With this new update, you can monitor exactly what has changed, providing you a finer grain of control, the possibility of greater configuration, and an improved interface.

How do they work and what can I do with them?

There are many things that you can do when your content changes. You may want to rebuild your website or application, notify your team, send a newsletter to your users, a post, a tweet, a facebook status, or re-sync your website cache.

Webhook triggers

There are now 6 events that you can configure to trigger a webhook call.

• When a document is published
• When a document is unpublished
• When a release is created
• When a release is edited or deleted
• When a tag is added (publicly)
• When a tag is deleted (publicly)

You can find the most recent triggers via the webhooks ‘Logs’ tab. From there, you’ll also be able to see the event details from the past 30 days.

Determining which documents have changed

Although this won't tell you if anything has been archived or deleted, you can keep a snapshot of your content. When you receive a webhook, you can query all of your content and compare this to your snapshot to see what has changed.

Configuring your webhook URL

To activate webhooks for your repository:

• Go to Settings / webhooks. you need to be the repository owner or to have admin rights to access it.
• Create a new webhook. You will need to enter the webhook URL (must be reachable from the Internet) and optionally a Secret that will function as a ”password" that will be added to your webhook request. If you do this we will send the content to your server so that you can verify that the request is coming from prismic.io.

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

• Select the corresponding type of triggers that you need.

Test your webhook

Once your webhook is added, you can trigger and test it at any time! Just click on the "Trigger it" button.

In case your server responds with anything other than a 2xx response, the delivery will be attempted every 10 minutes (up to 5 times).

You can test your webhooks with a service like RequestBin.com

Webhooks can still be fired off for the publication of a document, but you can now configure other triggers to cause the publication to fire; for example: configuring specific URLs for each one.

We've mentioned a few possible usages of webhooks, but the only limit is your imagination!

Let us know if you find a neat application for them or create a service integration. We love getting feedback and interesting use cases!

If you have any questions about these updates you can get in touch with us via the chat button in the bottom right corner.