Introducing prismic.io webhooks: integration with publishing and changes events

At prismic.io, one of our goals is to provide a developer friendly platform enabling you to make the best out of your content, be it in the way you present it, optimise it or how you choose to deliver it. This is why we provide a very advanced API design, with very nice querying and caching characteristics.

Today we're announcing webhooks so that your websites and apps can get notified whenever new changes are available in your API. This adds up to the pre-existing API capacities to open yet a new range of integration possibilities.

Let your application know about content changes

There are many things you can do when your content changes. You may want to notify your team, send a newsletter to your users or post a tweet or a facebook status. Some might even choose to regenerate a static site built with, say, baked.js. Or trigger a new build of their application. Or just prime some cache.

So how does that work?

Webhooks are events triggered whenever changes are pushed in a release, or when a collection or bookmark is modified. prismic.io then sends POST requests to user provided URLs, to let other parties react to the change. The request body is a JSON object containing data about the triggered event:

{
  "type": "api-update",
  "domain": "example",
  "apiUrl": "https://example.prismic.io/api",
  "secret": "mySecretPassphrase"
}

Manage your repository webhooks

Reach the Webhooks tab of the Settings menu: here comes the webhook creation form.

The only required field is the URL. This is your application URL, the endpoint where the POST request will be sent. Of course, this URL must be reachable from the Internet. The secret field is optional; if you set it, we'll send its content to your server, so that you can verify that the request is coming from prismic.io.

Once your webhook is added, you can trigger it manually to ensure that your server is reacting correctly to the POST call. If your server replies with 2xx HTTP status code, the delivery is considered successful. Any other status code (or a no response / timeout) will result in the delivery being retried 10 minutes later, up to 5 retries.

We've mentioned a few possible usages of webhooks, but the only limit is your imagination! If you find a neat application for them, or create a service integration, let us know. We love feedback!

This feature is being progressively deployed to more and more repositories. But feel free to ask if it is not available for you yet and you want to give it a try.