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: