Archive

Webhooks API

Create, update, delete, and log webhooks

Experimental feature

This article describes an experimental Sanity feature. The APIs described are subject to change and the documentation may not be completely accurate.

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.

Input

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.

Input

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

Input

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

Was this page helpful?