Webhooks API reference

Reference documentation for the Webhooks HTTP endpoints.

The Webhooks API lets you programmatically interact with and monitor webhooks.

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

Authentication

  • All requests must be authenticated.
  • Managing webhooks requires the webhooks permission on the project: read to list or get webhooks, create to create or update them, and delete to delete them.

Webhook types

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

Document webhooks

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

Transaction webhooks

A transaction webhook triggers once per dataset, meaning if you batch together multiple document mutations in one transaction, only one webhook is 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

  • typestringrequired

    Must be 'document'

  • namestringrequired

    Name of webhook

  • urlstringrequired

    The endpoint to which the webhook request is sent. Must start with http:// or https://, and must not resolve to a private address.

  • datasetstringrequired

    Which dataset should this trigger for. Use a dataset name (letters, numbers, _, and -, stored lowercase), or * for all datasets in the project.

  • descriptionstring|null

    Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired

      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 (*[])

    • 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. Use the format vYYYY-MM-DD, or vX.

  • httpMethodstringdefault: "POST"

    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

  • includeDraftsbooleandefault: false

    Set to trigger on changes to draft documents.

  • includeAllVersionsbooleandefault: false

    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. The total size of all headers can not exceed 2 kB. Header names can only contain letters, numbers, and hyphens, and values must be ASCII without line breaks. The content-length, connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade headers are not allowed.

  • secretstring|null

    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

  • Set to 'true' to disable the webhook and prevent it from triggering

  • idstring

    Unique identifier for the webhook

  • projectIdstring

    ID of the Sanity project

  • createdAtstring (date-time)

    Timestamp when the webhook was created

  • ID of the user who created the webhook

  • isDisabledboolean

    Whether the webhook is currently disabled

  • deletedAtstring|null (date-time)

    Timestamp when the webhook was deleted, if applicable

  • filterobject|nulldeprecated

    Legacy per-event filter object. Use rule.filter instead.

  • projectionobject|nulldeprecated

    Legacy per-event projection object. Use rule.projection instead.

Create a webhook

post/hooks/projects/{projectId}

Path parameters

Request body application/json

  • typestringrequired

    Must be 'document'

  • namestringrequired

    Name of webhook

  • urlstringrequired

    The endpoint to which the webhook request is sent. Must start with http:// or https://, and must not resolve to a private address.

  • datasetstringrequired

    Which dataset should this trigger for. Use a dataset name (letters, numbers, _, and -, stored lowercase), or * for all datasets in the project.

  • descriptionstring|null

    Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired

      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 (*[])

    • 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. Use the format vYYYY-MM-DD, or vX.

  • httpMethodstringdefault: "POST"

    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

  • includeDraftsbooleandefault: false

    Set to trigger on changes to draft documents.

  • includeAllVersionsbooleandefault: false

    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. The total size of all headers can not exceed 2 kB. Header names can only contain letters, numbers, and hyphens, and values must be ASCII without line breaks. The content-length, connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade headers are not allowed.

  • secretstring|null

    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

  • Set to 'true' to disable the webhook and prevent it from triggering

Responses

201

Created webhook

  • typestringrequired

    Must be 'document'

  • namestringrequired

    Name of webhook

  • urlstringrequired

    The endpoint to which the webhook request is sent. Must start with http:// or https://, and must not resolve to a private address.

  • datasetstringrequired

    Which dataset should this trigger for. Use a dataset name (letters, numbers, _, and -, stored lowercase), or * for all datasets in the project.

  • descriptionstring|null

    Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired

      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 (*[])

    • 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. Use the format vYYYY-MM-DD, or vX.

  • httpMethodstringdefault: "POST"

    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

  • includeDraftsbooleandefault: false

    Set to trigger on changes to draft documents.

  • includeAllVersionsbooleandefault: false

    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. The total size of all headers can not exceed 2 kB. Header names can only contain letters, numbers, and hyphens, and values must be ASCII without line breaks. The content-length, connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade headers are not allowed.

  • secretstring|null

    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

  • Set to 'true' to disable the webhook and prevent it from triggering

  • idstring

    Unique identifier for the webhook

  • projectIdstring

    ID of the Sanity project

  • createdAtstring (date-time)

    Timestamp when the webhook was created

  • ID of the user who created the webhook

  • isDisabledboolean

    Whether the webhook is currently disabled

  • deletedAtstring|null (date-time)

    Timestamp when the webhook was deleted, if applicable

  • filterobject|nulldeprecated

    Legacy per-event filter object. Use rule.filter instead.

  • projectionobject|nulldeprecated

    Legacy per-event projection object. Use rule.projection instead.

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 endpoint to which the webhook request is sent. Must start with http:// or https://, and must not resolve to a private address.

  • datasetstringrequired

    Which dataset should this trigger for. Use a dataset name (letters, numbers, _, and -, stored lowercase), or * for all datasets in the project.

  • descriptionstring|null

    Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired

      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 (*[])

    • 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. Use the format vYYYY-MM-DD, or vX.

  • httpMethodstringdefault: "POST"

    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

  • includeDraftsbooleandefault: false

    Set to trigger on changes to draft documents.

  • includeAllVersionsbooleandefault: false

    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. The total size of all headers can not exceed 2 kB. Header names can only contain letters, numbers, and hyphens, and values must be ASCII without line breaks. The content-length, connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade headers are not allowed.

  • secretstring|null

    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

  • Set to 'true' to disable the webhook and prevent it from triggering

  • idstring

    Unique identifier for the webhook

  • projectIdstring

    ID of the Sanity project

  • createdAtstring (date-time)

    Timestamp when the webhook was created

  • ID of the user who created the webhook

  • isDisabledboolean

    Whether the webhook is currently disabled

  • deletedAtstring|null (date-time)

    Timestamp when the webhook was deleted, if applicable

  • filterobject|nulldeprecated

    Legacy per-event filter object. Use rule.filter instead.

  • projectionobject|nulldeprecated

    Legacy per-event projection object. Use rule.projection instead.

Update a webhook

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

Path parameters

Request body application/json

  • namestring

    Name of webhook

  • urlstring

    The endpoint to which the webhook request is sent

  • datasetstring

    Which dataset should this trigger for. '*' means all datasets in the project

  • Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired
      Show child attributes
      items
      • string
        enum:"create", "update", "delete"
    • filterstring

      GROQ filter specifying which documents trigger the webhook

    • GROQ projection defining the payload of the webhook request

  • Which API version to use for the GROQ filter and projection. Use the format vYYYY-MM-DD, or vX.

  • HTTP method of the webhook request

  • Set to trigger on changes to draft documents.

  • Set to trigger on changes to version documents.

  • headersobject

    Additional HTTP headers sent with the webhook request

  • secretstring

    Secret used to sign outgoing webhook requests

  • Set to 'true' to disable the webhook and prevent it from triggering

Responses

200

Updated webhook

  • typestringrequired

    Must be 'document'

  • namestringrequired

    Name of webhook

  • urlstringrequired

    The endpoint to which the webhook request is sent. Must start with http:// or https://, and must not resolve to a private address.

  • datasetstringrequired

    Which dataset should this trigger for. Use a dataset name (letters, numbers, _, and -, stored lowercase), or * for all datasets in the project.

  • descriptionstring|null

    Optional description to add helpful context to the webhook

  • ruleobject

    Configuration for when and how the webhook should trigger

    Show child attributes
    • onarrayrequired

      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 (*[])

    • 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. Use the format vYYYY-MM-DD, or vX.

  • httpMethodstringdefault: "POST"

    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

  • includeDraftsbooleandefault: false

    Set to trigger on changes to draft documents.

  • includeAllVersionsbooleandefault: false

    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. The total size of all headers can not exceed 2 kB. Header names can only contain letters, numbers, and hyphens, and values must be ASCII without line breaks. The content-length, connection, keep-alive, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, and upgrade headers are not allowed.

  • secretstring|null

    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

  • Set to 'true' to disable the webhook and prevent it from triggering

  • idstring

    Unique identifier for the webhook

  • projectIdstring

    ID of the Sanity project

  • createdAtstring (date-time)

    Timestamp when the webhook was created

  • ID of the user who created the webhook

  • isDisabledboolean

    Whether the webhook is currently disabled

  • deletedAtstring|null (date-time)

    Timestamp when the webhook was deleted, if applicable

  • filterobject|nulldeprecated

    Legacy per-event filter object. Use rule.filter instead.

  • projectionobject|nulldeprecated

    Legacy per-event projection object. Use rule.projection instead.

Delete a webhook

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

Path parameters

Responses

200

Deleted webhook

List webhook attempts

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

Path parameters

Query parameters

  • offsetintegerdefault: 0

    Number of attempts to skip before returning results

  • limitintegerdefault: 25

    Number of attempts to return

  • statestring

    Only return successful or failed attempts

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|null

      Response body 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. Document webhooks always report other for failed attempts.

    • resultCodeinteger|null

      HTTP status code from the webhook endpoint, or null if no response was received

    • 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 attempts for a webhook message

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

Path parameters

  • projectIdstringrequired
  • idstringrequired

    ID of the webhook

  • messageIdstringrequired

    ID of the webhook message

Query parameters

  • offsetintegerdefault: 0

    Number of attempts to skip before returning results

  • limitintegerdefault: 25

    Number of attempts to return

  • statestring

    Only return successful or failed attempts

Responses

200

List of attempts for the message

    items
    • idstring

      Unique identifier for the webhook attempt

    • projectIdstring

      ID of the Sanity project

    • inProgressboolean

      Whether the webhook attempt is currently in progress

    • resultBodystring|null

      Response body 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. Document webhooks always report other for failed attempts.

    • resultCodeinteger|null

      HTTP status code from the webhook endpoint, or null if no response was received

    • 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

Get a webhook attempt by ID

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

Returns a single delivery attempt for a transaction webhook. Attempts for document webhooks are not available from this endpoint and return 404; use the attempt list endpoints for the webhook instead.

Path parameters

Responses

200

Webhook attempt details

  • idstring

    Unique identifier for the webhook attempt

  • projectIdstring

    ID of the Sanity project

  • inProgressboolean

    Whether the webhook attempt is currently in progress

  • resultBodystring|null

    Response body 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. Document webhooks always report other for failed attempts.

  • resultCodeinteger|null

    HTTP status code from the webhook endpoint, or null if no response was received

  • 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/projects/{projectId}/{id}/messages

Path parameters

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

    • Number of times the message has failed

    • resultCodeinteger|null

      HTTP status code from the most recent response from the webhook endpoint

    • statusstring

      Status of the message. Document webhooks can also report transientFailure and canceled.

    • payloadstring

      Payload of the message as defined by the webhook rule.

    • Delivery attempts for the message, newest first. Document webhooks only.

      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 attempt was made

      • updatedAtstring (date-time)

        Timestamp when the attempt 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|null

        Response body from the webhook endpoint, or null if no response was received

      • isFailureboolean

        Whether the attempt failed

      • failureReasonstring|null

        other if the attempt failed, otherwise null.

      • resultCodeinteger|null

        HTTP status code from the webhook endpoint, or null if no response was received

    • hookIdstring

      ID of the webhook. Transaction webhooks only.

    • updatedAtstring (date-time)

      Timestamp when the message was last updated. Transaction webhooks only.

    • deletedAtstring|null (date-time)

      Timestamp when the message was deleted, if applicable. Transaction webhooks only.

sanity.ioAll Systems Operational© Sanity 2026
Change site theme