Skip to content
✨Discover storytelling in the AI age with Pixar's Matthew Luhn at Sanity Connect, May 8th—register now
Experimental feature

Webhooks API

Create, update, delete, and log webhooks

Webhook configuration fields

  • type: document
  • description: A 1024 character long string without any validation. Default: null
  • includeDrafts: A boolean which allows webhooks to be processed for drafts. Default: false
  • httpMethod (one of GET, POST, PUT, PATCH and DELETE; defaults to POST). HTTP method with which payload will be delivered. Note that a body that is same as projection is sent in all the methods. (Note: Transaction-based webhooks always use POST method.)
  • headers: Supported only for document-based webhooks. A object of key-value pair (string-string) which define static headers that will be sent as request headers by delivery system to remote URL.
  • filter: An object with keys always, create, update and delete (mutation types) defining delta-groq filters.
  • projection: An object with keys create, update and delete (mutation types) defining delta-groq projections. Request body to remote host is strictly set to projection.
  • apiVersion: GROQ query API version to use with filters and projections. Delta GROQ syntax is only available after v2021-03-25. Validation happens with groq-js.
  • secret: Secret for signature. See below.
{
  type: 'document',
  filter: {
    always: string || null,
    create: string || null,
    update: string || null,
    delete: string || null
  },
  projection: {
    always: string || null,
    create: string || null,
    update: string || null,
    delete: string || null
  },
  apiVersion: string,
  includeDrafts: boolean,
  id: string,
  name: string,
  projectId: string,
  dataset: string,
  url: string,
  createdByUserId: string,
  isDisabled: boolean || false,
  isDisabledByUser: boolean || false,
  deletedAt: timestamp,
  description: string || null,
  httpMethod: string || 'POST',
  headers: object || null,
	secret: string
}

Endpoints

All requests needs to be authenticated with a token that has manage permissions [CHECK IF CORRECT].

Get all webhooks

GET /v2021-03-25/hooks/projects/:projectId

Returns a list of all webhooks on a project. The webhooks are ordered by creation date, with the oldest webhook appearing first.

Request

curl GET 'https://api.sanity.io/vX/hooks/projects/<projectId>' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  {
    "type": "document",
    "rule": {
      "on": [
        "update"
      ],
      "filter": "delta::changedAny(title)",
      "projection": "{\n  _type,\n  _id,\n  \"change\": \"the title \" + before().title + \" was changed to \" + after().title\n}"
      },
    "apiVersion": "v2021-03-25",
    "httpMethod": "POST",
    "includeDrafts": false,
    "headers": {},
    "secret": null,
    "id": "mEHeELLK1YWGV8Ek",
    "name": "GROQ-powered webhook demo",
    "projectId": "3do82whm",
    "dataset": "production",
    "url": "https://webhook.site/ce874d3a-56b9-41f5-be28-c8e7aadda1d0",
    "createdByUserId": "pEuO2i51F",
    "isDisabled": false,
    "isDisabledByUser": false,
    "deletedAt": null,
    "description": "Desc"
  }
]

Create new webhook

POST /vX/hooks/projecst/:projectId

Creates a new webhook on a project.

Request

curl GET 'https://api.sanity.io/vX/hooks/projects/<projectId>' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "type": "document",
    "rule": {
      "on": [
        "update"
      ],
      "filter": "delta::changedAny(title)",
      "projection": "{\n  _type,\n  _id,\n  \"change\": \"the title \" + before().title + \" was changed to \" + after().title\n}"
      },
    "apiVersion": "v2021-03-25",
    "httpMethod": "POST",
    "includeDrafts": false,
    "headers": {},
    "secret": null,
    "name": "GROQ-powered webhook demo",
    "projectId": "3do82whm",
    "dataset": "production",
    "url": "https://webhook.site/ce874d3a-56b9-41f5-be28-c8e7aadda1d0",
    "isDisabled": false,
    "deletedAt": null,
    "description": "Demonstrates how webhooks work"
  }'

Response

[
  {
    "type": "document",
    "rule": {
      "on": [
        "update"
      ],
      "filter": "delta::changedAny(title)",
      "projection": "{\n  _type,\n  _id,\n  \"change\": \"the title \" + before().title + \" was changed to \" + after().title\n}"
      },
    "apiVersion": "v2021-03-25",
    "httpMethod": "POST",
    "includeDrafts": false,
    "headers": {},
    "secret": null,
    "id": "mEHeELLK1YWGV8Ek",
    "name": "GROQ-powered webhook demo",
    "projectId": "3do82whm",
    "dataset": "production",
    "url": "https://webhook.site/ce874d3a-56b9-41f5-be28-c8e7aadda1d0",
    "createdByUserId": "pEuO2i51F",
    "isDisabled": false,
    "isDisabledByUser": false,
    "deletedAt": null,
    "description": "Demonstrates how webhooks work"
  }
]

Update webhook

PUT /vX/hooks/projects/:projectId/:webhookId

Request

curl GET 'https://api.sanity.io/vX/hooks/projects/<projectId>' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "rule": {
      "on": [
        "update"
      ],
      "filter": "_type == \"post\" && delta::changedAny(title)",
      "projection": "{\n  _id,\n  \"change\": \"The post title \" + before().title + \" was changed to \" + after().title\n}"
      }
  }'

Response

[
  {
    "type": "document",
    "rule": {
      "on": [
        "update"
      ],
      "filter": "_type == \"post\" && delta::changedAny(title)",
      "projection": "{\n  _id,\n  \"change\": \"The post title \" + before().title + \" was changed to \" + after().title\n}"
      },
    "apiVersion": "v2021-03-25",
    "httpMethod": "POST",
    "includeDrafts": false,
    "headers": {},
    "secret": null,
    "id": "mEHeELLK1YWGV8Ek",
    "name": "GROQ-powered webhook demo",
    "projectId": "3do82whm",
    "dataset": "production",
    "url": "https://webhook.site/ce874d3a-56b9-41f5-be28-c8e7aadda1d0",
    "createdByUserId": "pEuO2i51F",
    "isDisabled": false,
    "isDisabledByUser": false,
    "deletedAt": null,
    "description": "Demonstrates how webhooks work"
  }
]

Delete webhook

DELETE /vX/hooks/projects/:projectId/:webhookId

Updated on December 7, 2022

Was this article helpful?