Send customized HTTP requests when something in your content lake has changed. Use GROQ to define which documents should trigger a webhook and what its payload should be.

Webhooks at a glance

Webhooks are a way to integrate applications with automated HTTP requests. Typically you use it to connect services by creating a special URL that accepts incoming requests. What happens when the request resolves depends on the application or service.

Some services only support receiving webhooks; others can both receive and send them. The Sanity Content Lake supports both sophisticated outgoing webhooks, and receiving incoming webhooks to any appropriate API endpoint, provided they have the proper payload and authentication.

Webhooks in your Sanity Content Lake

You can create and manage outgoing webhooks in the API section of your project settings, which you'll find at sanity.io/manage. Webhooks can also be managed through the CLI or directly through the project APIs.

Configuration

The following fields are available for webhooks. You can find them all under the webhooks section under the API in your project's settings on sanity.io/manage.

Name and description

You can name your webhooks and give them a description. The description field, while optional, is a useful way to add helpful context about your webhook.

URL

The URL field is where you specify the endpoint to which the webhook request is sent. If you want to test the webhook before entering the production endpoint, you can use services like webhook.site, or Beeceptor. You can also use ngrok or Localtunnel to test a hook against your local environment.

Trigger on

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 in question.

Filter

A GROQ filter specifying which documents will, when changed, trigger your webhook. A filter is what you commonly see between the *[ and ] in a GROQ query. This field supports all the GROQ functions you'd expect and has additional support for functions in the delta:: namespace, as well as before() and after().

If left empty, it will apply to all documents (*[]).

Webhook filter does not support the following kind of queries and will just yield to false:

• Sub-queries, e.g. _type == "book" && author._ref in *[_type=="author" && name=="John Doe"]._id
• Cross dataset references: _type == "book" && author->featured where author is a cross-dataset reference.

See our Intro to Filters guide for tips on using filters in webhooks.

Projection

A GROQ projection defining the payload (or body) of the outgoing webhook request. This field supports GROQ functions in the delta:: namespace, as well as before() and after().

If left empty, it will include the whole document after the change that triggered it.

See our Intro to Projections guide for tips on using projections in webhooks.

Status

Enable or disable your webhook.

HTTP method

This field configures the webhook's HTTP request method. It can be set to POST, PUT, PATCH, DELETE, or GET. Some endpoints require incoming requests to use a specific method to work.

HTTP headers

Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request.

A webhook will always include the following headers and values:

• connection: close
• accept-encoding: gzip
• idempotency-key: <a unique key> See documentation below.
• content-type: application/json
• content-length: <the length of the payload in bytes>
• user-agent: Sanity.io webhook delivery
• host: <the endpoint URL host>

As well as the following Sanity-specific headers that can be useful for logging and debugging your webhooks:

• sanity-transaction-id: ID of transaction.
• sanity-transaction-time: Timestamp of transaction.
• sanity-dataset: Name of dataset (also available in projection today as sanity::dataset()).
• sanity-document-id: Document ID being notified about.
• sanity-project-id: ID of project (also available in projection today as sanity::projectId()).
• sanity-webhook-id: ID of webhook.
• sanity-operation: Either create, update or delete

API version

Defaults to the v2021-03-25 of the query API. Can be overridden using the Webhooks API in cases where you want to create webhooks with old behavior that might have been deprecated.

Drafts and versions

By default, documents in the drafts. and versions. ID-namespace will be automatically ignored. Enable the drafts or version setting if you want the triggers and filter to apply to draft or version documents. Note: version support was added in version 2025-02-19.

Secret

To let receiving services verify the origin of any outgoing webhook, you may add a secret that will be hashed and included as part of the webhook request's headers. You may find our webhook toolkit library helpful for working with secrets. If you want to roll your own; we model the encryption and decryption of secrets on the same standard as Stripe.

Idempotency-key

Requests include a new header that can be used to de-duplicate deliveries: idempotency-key.

This is necessary because webhooks will sometimes be retried, and our system has at least one delivery. Using the unique idempotency key lets the receiver ignore messages it has already received.

We follow this new draft standard for idempotency.

Sharing webhooks

Webhook configurations can be shared with a URL. This is practical if you want to quickly repurpose webhooks across projects or share with the community. You can generate a share URL by going to sanity.io/manage/webhooks/share or by finding the share button in the three-dot-menu in the webhooks overview.

Debugging webhooks

You can find the attempts log if you click the three-dotted menu for a given webhook. The log will include information about the response a webhook request got. The attempts log is available as an API endpoint at:

Message log

The message log is available as an API endpoint at:

The log contains a list of messages in the queue and any delivery attempts for each:

• If all the messages returned have the status queued then your processing has fallen behind. This may indicate that your webhook processing is too slow and/or that your webhook filter is too broad and is generating a vast number of messages.
• If your webhook request handler takes longer to process a message than the rate at which you are generating changes that trigger the webhook then the queue will never be cleared.

HTTP Status codes

The HTTP status codes are used to determine if delivery is successful:

• 200-range will be treated as a success
• 400-range will be treated as undeliverable, as the server said it was a client error (with one exception—see next item)
• 429 will be retried according to the retry policy outlined below
• 500-range will be retried according to the retry policy outlined below

Technical limits, retry policy, and timeouts

Webhooks are limited to 1 concurrent request.

We will retry sending a webhook request twice, with a 30 second interval between each attempt. This limit is subject to change in the future.

A webhook request will time out after 30 seconds.

Webhooks origin IP addresses

The full list of IP addresses that Sanity webhooks calls originate from, can be found on this file:

https://www.sanity.io/files/webhooks-egress-ips.txt

The IP addresses generally don’t change but they may be updated from time to time, on planned or unplanned/emergency maintenance. For planned changes, we aim to announce upcoming changes 7 days in advance on Sanity’s status page feed here: https://www.sanity-status.com/. Unplanned maintenance changes will happen without notice, but the URL file will be immediately up-to-date.