GROQ-Powered Webhooks – Intro to Filters

A thorough intro to using GROQ-filters in a webhook-context

GROQ-powered webhooks give you precise control over the circumstances and conditions under which your webhooks will trigger. In this article, we'll take a closer look at the possibilities offered by GROQ filters.

The two GROQ super-powers webhooks have are filters and projections. The latter enables you to construct your request's payload to your exact needs and is discussed in an article of its own. In this article, we'll be discussing the former. Filters let you define the circumstances and conditions under which your webhook should trigger with immaculate precision.

If you want to follow along, go ahead and set up a new webhook in the project management console. You can use a service like webhook.site, or Beeceptor to debug and test your webhook.

Before dedicating our attention exclusively to GROQ-filters, let's briefly look at the set of checkboxes labeled "Trigger on", found immediately before the filter input field.

Webhooks can be triggered when a document is created, updated, deleted, or any combination of these.

• Create - triggers on the creation of a new document.
• Update - triggers on every change to a document once created.
• Delete - triggers on the deletion of a document

Between these, you'll be able to react to all major interactions with the documents relevant to you – the selection of which we'll be spending the rest of this article getting increasingly particular about.

This is where, using GROQ, you define the criteria by which a document event should trigger your webhook. If you are already familiar with GROQ, the filter is the bit that you'll often see inside the square brackets at the start of your query, often preceded by an asterisk.

*[ /*Filters go here!*/ ]

A typical case of using a filter in a query might look something like this:

// Returns every document with a type of post 
*[_type == "post"]

When creating filters for our webhooks we skip the asterisk and square brackets and just type the filtering conditions right into the input field. Translating the scenario from above, our webhook filter would look like this:

This minimal example is already a quite powerful feature – enabling you to react to changes to specific types of content – but let's get a bit more creative! Let's expand our filter to check for the value of a boolean field named featured in the document, and only trigger if it's set to true, and just to make it interesting let's add another document type called article as well.

// Trigger on events for posts and articles with featured set to true
_type in ["post", "article"] && featured == true

Just as in normal GROQ-queries you can use logical operators to filter on a range of different field types, and you can combine any number of these in order to get exactly the result you want.

// Trigger on events for movies that are quite popular and relatively recent
_type == "movie" && popularity > 15 && releaseDate > "2016-01-01"

// Trigger on events for articles tagged with a carefree attitude
_type == "article" && "yolo" in tags

// Trigger on events for posts about extraterrestrials 
_type == "post" && body[].children[].text match "alien"

Following references to filter on content in the referenced document also works as you'd expect:

// Trigger on events for posts by a specific author
_type == "post" && author->name == "Sinjoro Ajnulo"

You can also use GROQ functions, such as dateTime(), references(), or defined().

// Trigger on events for posts published after 2016-01-01
_type == "post" && dateTime(_createdAt) > dateTime("2016-01-01T00:00:00Z")

// Trigger on events for books with a value set for the author field
_type == "book" && defined(author)

// Trigger on events for books referencing a specific author
_type == "book" && references("sinjoro-ajnulo")

Namespaced functions are also available, such as pt::text() which gives you a plain text version of any Portable Text rich text field, or the sanity::-prefixed functions which are helpful for querying about the environment from which the webhook was triggered.

// Trigger on events for posts that mention a certain term in the body
_type == "post" && pt::text(body) match "Sinjoro"

// Trigger if the projectId matches the expected value
sanity::projectId() == "<projectId>"

// Trigger if the change occurred in one of the specified datasets
sanity::dataset() in ["test", "staging"]

Delta-GROQ is an extension to the GROQ language designed specifically to enable you to reason about changes made to a document. Currently, the following delta-functions are available:

• before() – returns the matching documents as they were before the change.
• after() – returns the matching documents after the change.
• delta::changedAny() – returns true if specified field values have changed.
• delta::changedOnly() – which returns true if only specified field values have changed.

The aptly named functions before()and after() let you compare the document in its entirety before and after the change event was executed. You may also use dot notation to check the value of any single field. E.g. before().title == after().title.

// Trigger if the price has gone down
_type == "product" && before().price > after().price

// Trigger if title changes to no longer including the string 'DRAFT'
before().title match "DRAFT*" && !(after().title match "DRAFT*")

The namespaced functions delta::changedAny() and delta::changedOnly() are helpful when you want to run the webhook only when certain fields have been updated, or indeed if only certain fields have been updated.

// Trigger if one or more of the specified fields have been updated
_type == "product" && delta::changedAny((name, price, stock))

// Do not trigger if featured is the only field updated
_type == "product" && !delta::changedOnly(featured)

In this article we've demonstrated some more or less plausible examples of how using GROQ filters enables unmatched granularity in specifying the circumstances and conditions under which your webhooks should be triggered. While we've touched upon a number of different methods and techniques, we haven't even revealed the tip of the iceberg representing the capabilities of GROQ. For inspiration, check out the GROQ Query Cheat Sheet!