HTTP API ReferenceLast updated January 9, 2026

Webhooks API reference

Reference documentation for the Webhooks HTTP endpoints.

The Webhooks API allows you to programmatically interact with and monitor webhooks.

GROQ-powered webhooks

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.

Webhook Best Practices

Learn best practices about configuration and handling of webhooks

In addition to webhooks, you can also react to document changes with Sanity Functions.

Authentication

All requests must be authenticated.
Manipulating documents requires read+write access permission for the affected document type. In most cases, this includes the Editor, Developer, or Administrator roles.

Webhook types

Sanity provides two types of webhooks, transaction and document. Document webhooks are preferred because they are more flexible and powerful.

A document webhook triggers every time a document is created, updated, or deleted. If a transaction updates 3 documents, 3 webhooks will be executed. Document webhook also allows for more granular filtering and customizable payloads with GROQ.

Transaction

A transaction webhook triggers once per dataset, meaning if you batch together multiple document mutations in one transaction only one webhook will be executed.

Base API server URL

Sanity API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

projectIdstringdefault: "projectId"
Project ID
apiVersionstringdefault: "v2025-02-19"
API version

Endpoints

List all webhooks

get/hooks/projects/{projectId}

Path parameters

projectIdstringrequired

Responses

200

List of webhooks

items

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering
createdAtstring (date-time)
Timestamp when the webhook was created
isDisabledboolean
Whether the webhook is currently disabled
deletedAtstring|null (date-time)
Timestamp when the webhook was deleted, if applicable

Create a webhook

post/hooks/projects/{projectId}

Path parameters

projectIdstringrequired

Request body `application/json`

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering

Responses

200

Created webhook

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering
createdAtstring (date-time)
Timestamp when the webhook was created
isDisabledboolean
Whether the webhook is currently disabled
deletedAtstring|null (date-time)
Timestamp when the webhook was deleted, if applicable

Get a webhook by ID

get/hooks/projects/{projectId}/{id}

Path parameters

projectIdstringrequired
idstringrequired

Responses

200

Webhook details

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering
createdAtstring (date-time)
Timestamp when the webhook was created
isDisabledboolean
Whether the webhook is currently disabled
deletedAtstring|null (date-time)
Timestamp when the webhook was deleted, if applicable

Update a webhook

patch/hooks/projects/{projectId}/{id}

Path parameters

projectIdstringrequired
idstringrequired

Request body `application/json`

isDisabledByUserboolean

Responses

200

Updated webhook

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering
createdAtstring (date-time)
Timestamp when the webhook was created
isDisabledboolean
Whether the webhook is currently disabled
deletedAtstring|null (date-time)
Timestamp when the webhook was deleted, if applicable

Delete a webhook

delete/hooks/projects/{projectId}/{id}

Path parameters

projectIdstringrequired
idstringrequired

Responses

200

Deleted webhook

idstring
deletedinteger

List webhook attempts

get/hooks/projects/{projectId}/{id}/attempts

Path parameters

projectIdstringrequired
idstringrequired

Responses

200

List of webhook attempts

items

idstring
Unique identifier for the webhook attempt
projectIdstring
ID of the Sanity project
inProgressboolean
Whether the webhook attempt is currently in progress
resultBodystring
Response body from the webhook endpoint
resultCodeinteger
HTTP status code from the webhook endpoint
durationinteger
Duration of the webhook attempt in milliseconds
isFailureboolean
Whether the webhook attempt failed
failureReasonstring|null
Reason for failure if the webhook attempt failed
createdAtstring (date-time)
Timestamp when the webhook attempt was created
updatedAtstring (date-time)
Timestamp when the webhook attempt was last updated
deletedAtstring|null (date-time)
Timestamp when the webhook attempt was deleted, if applicable
messageIdstring
Unique identifier for the message that triggered the webhook
hookIdstring
ID of the webhook that was triggered

List webhook messages

get/hooks/{id}/messages

Path parameters

idstringrequired
ID of the webhook

Query parameters

limitintegerdefault: 25
Number of messages to return
offsetintegerdefault: 0
Number of messages to skip before returning results

Responses

Select response

200

List of webhook messages

items

idstring
Unique identifier for the webhook message
createdAtstring (date-time)
Timestamp when the message was created
projectIdstring
ID of the Sanity project
datasetstring
Which dataset the message belongs to
failureCountinteger
Number of times the message has failed
resultCodeinteger
HTTP status code from the webhook endpoint
statusstring
Status of the message
payloadstring
Payload of the message as defined by the webhook rule.
attemptsarray
Show child attributes
items
- idstring
  Unique identifier for the webhook attempt
- inProgressboolean
  Whether the attempt is currently in progress
- createdAtstring (date-time)
  Timestamp when the message was created
- updatedAtstring (date-time)
  Timestamp when the message was last updated
- messageIdstring
  ID of the webhook message that the attempt belongs to
- hookIdstring
  ID of the webhook that was triggered
- durationinteger
  Duration of the attempt in milliseconds
- projectIdstring
  ID of the Sanity project
- resultBodystring
  Response body from the webhook endpoint
- isFailureboolean
  Whether the attempt failed
- failureReasonstring
- resultCodeinteger
  HTTP status code from the webhook endpoint

Create a webhook

post/hooks/projects/{projectId}

Path parameters

projectIdstringrequired

Request body `application/json`

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering

Responses

200

Created webhook

Select one

typestringrequired
Must be 'document'
namestringrequired
Name of webhook
urlstringrequired
The URL field is where you specify the endpoint to which the webhook request is sent
datasetstringrequired
Which dataset should this trigger for. '*' means all datasets in the project
descriptionstring
Optional description to add helpful context to the webhook
ruleobject
Configuration for when and how the webhook should trigger
Show child attributes
- onarray
  Webhooks can be triggered when a document is created, updated, deleted, or any combination of these
  Show child attributes
  items
  string
  enum:"create", "update", "delete"
- filterstring
  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 (*[])
- projectionstring
  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
apiVersionstringrequired
Which API version to use for the GROQ filter and projection.
httpMethodstring
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
includeDraftsboolean
Set to trigger on changes to draft documents.
includeAllVersionsboolean
Set to trigger on changes to version documents.
headersobject
Additional HTTP headers. You can add multiple headers. A common example is adding an Authorization: Bearer <token> header to authenticate the webhook request
secretstring
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
isDisabledByUserboolean
Set to 'true' to disable the webhook and prevent it from triggering
createdAtstring (date-time)
Timestamp when the webhook was created
isDisabledboolean
Whether the webhook is currently disabled
deletedAtstring|null (date-time)
Timestamp when the webhook was deleted, if applicable

GROQ-powered webhooks

Webhook Best Practices

Authentication

Webhook types

Document

Transaction

Base API server URL

Variables

Endpoints

List all webhooks

Path parameters

Responses

items

items

Create a webhook

Path parameters

Request body application/json

items

Responses

items

Get a webhook by ID

Path parameters

Responses

items

Update a webhook

Path parameters

Request body application/json

Responses

items

Delete a webhook

Path parameters

Responses

List webhook attempts

Path parameters

Responses

items

List webhook messages

Path parameters

Query parameters

Responses

items

items

Endpoints

List all webhooks

Path parameters

Responses

items

items

Create a webhook

Path parameters

Request body application/json

items

Responses

items

Get a webhook by ID

Path parameters

Responses

items

Update a webhook

Path parameters

Request body application/json

Responses

items

Delete a webhook

Path parameters

Responses

List webhook attempts

Path parameters

Responses

items

List webhook messages

Path parameters

Query parameters

Responses

items

items

Request body `application/json`

Request body `application/json`

Request body `application/json`

Request body `application/json`