Introducing GROQ-powered Webhooks

Written by Marcus Sarmento

We’re releasing a brand new GROQ-powered Webhooks system that offers unprecedented granularity and customization for those that need to send or sync and send data to external systems. This new webhooks system is available on all plans starting today, with caps on the number of webhooks you can have configured at once and the time we’ll retry the webhook if it fails on the first attempt. GROQ-powered Webhooks are the latest way we enable you to treat content as data, letting you reimagine what’s possible with your content.

Read on to learn more about what this is and the value it provides.

What are webhooks?

Webhooks are a way for you to send data to another service when a particular event, that you define, happens.

You can think of webhooks as a kind of API. It’s common for APIs to let a client or consumer send a request to get or change some data; webhooks automatically send data as soon as the event in question happens. You can use webhooks to do things like send order data to a shipping service when someone completes a purchase or send a notification to the editor team when someone has changed some marketing copy. Our friends at the Syntax.fm podcast just recently did a webhooks-themed episode that provides a great overview of what they are and how they are used.

What is GROQ?

To understand why our new webhooks system is so unique, it’s important to first understand GROQ.

Graph-Relational Object Queries (GROQ) is a query language for JSON that lets you find documents and shape the output of that data however you want. It’s open-source and built for use on Sanity’s platform for structured content.

Combining GROQ with webhooks gives you a way to have full control over trigger conditions, and how you shape the data you want to eventually send in the webhook’s payload. This release also extends the GROQ in the content lake with a new delta namespace: You can now filter and project on a document’s state before and after a change has happened within the context of webhooks.

Introducing GROQ-powered Webhooks

Our new, GROQ-powered Webhooks are a huge leap forward for everyone that uses Sanity to sync and push data to external systems. We’ve found most webhooks systems out there have key limitations that make it harder for you and your team to do what you want to accomplish. Solutions from CMSes typically only support document-level triggers and don’t give you many options for customizing the webhook payload. But what if you wanted to do something useful like trigger a webhook based on a field-level change and return a value from a referenced document? Or maybe you want to trigger a webhook only when a price has decreased in a product document. Or include the title field before and after it changed in the payload. Now you can do that with Sanity’s new webhooks system.

GROQ-powered Webhooks come with 2 key features – Filters and Projections.

Filters let you precisely specify which documents and changes a webhook should trigger on. These can be defined on document-level, field-level, or even GROQ query-level changes, creations, or deletions of your content. Using GROQ, you can compare two states of a document and filter on any condition you want. For example, only trigger a webhook for documents of the type “product” and where the price has changed to be lower:

_type == “product” && before().price > after().price

Projections give you the ability to define the included payload of the webhook request’s body should be. Projections let you select and reshape whatever data is included in the document, including any documents it references. You can take this data and POST, PUT, PATCH, or DELETE it when sending it to other systems. For example, you can decide that the webhook should only include the title and the price of the product document that changed. Or include the category names it has references to, and the price before and after the change happened.

{
  title, 
  "beforePrice": before().price, 
  "afterPrice": after().price, 
  categories[]->{name} 
}

What makes our GROQ-powered Webhooks system special is the granularity and customization we provide. By letting you specify fine-grained Filters using GROQ, we let you focus on the specific actions and triggers you are most interested in without creating extra noise that you have to sift through later on. And since Projections are super customizable, you can pick and choose the data that is most important to send to other systems and effectively eliminate any extra development work needed to scrub the data.

What if your webhook fails to deliver the information to the external system for whatever reason? Don’t worry, we got you covered. GROQ-powered Webhooks are designed to retry the message for a set time period (depending on your plan). That helps ensure the delivery of the data you want to send from Sanity for a more reliable information flow.

Other improvements

In addition to the filter and projection functionality, we’ve made a bunch of other improvements as well:

There’s a new UI for webhooks in the management interface and a full RESTful API
Webhooks can now be edited after you have created them
You can enable and disable webhooks
Webhook entries contain more metadata, including name, description, and more
You can add custom headers, and specify its HTTP method
There’s a new attempts log that makes troubleshooting and testing easier
Webhooks support a secret that will be hashed in the request which you can use to authenticate that the request originates from your project
We include idempotency keys in the headers, which you can use when syncing data to verify you haven’t received it before
Webhook configurations can be shared via URL
Webhooks are now guaranteed to include the content changes that caused them
Webhooks will now be retried (and are also rate-limited to 60 per second)
We also added a sanity namespace to GROQ that can be used in projections

Examples

Webhooks are a general concept that can be used in nearly limitless ways. To help spur your imagination, we’ve created these guides to showcase different ways you can use our new GROQ-powered webhooks:

Our new webhooks system is a great way to ensure your data is synced with the other parts of your stack and sent to all the places you need. And because it’s built on GROQ, you can apply the power of the query language to webhooks so you can filter out the noise and ensure only the data you want is sent. It’s worth noting that our old webhooks system will be scheduled for deprecation, but you can follow this guide that shows how to recreate your old webhooks in the new GROQ-powered Webhooks system we’re launching today.

Check out the docs for more information, and do try out our new GROQ-powered Webhooks! We’re excited to see what you build with them.