HTTP API Reference

Webhooks API reference

Reference documentation for the Webhooks HTTP endpoints.

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

Want to get started?

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.

Document

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

Responses

200

List of webhooks

items
  • 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

Request body application/json

  • 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

  • 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

Responses

200

Webhook details

  • 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

Request body application/json

Responses

200

Updated webhook

  • 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

List webhook attempts

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

Path parameters

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

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