Webhooks (Legacy)

Webhooks allow you to build or set up applications which subscribe to events inside of your Sanity datasets. When an event is triggered, we'll send an HTTP POST payload to the webhook's configured URL. Webhooks can be used to send emails when documents are published, trigger a website build, update a backup, notify Slack when content changes and many other creative and useful scenarios. You're only limited by your imagination.

A webhook is called every time a published document is changed, created or deleted. If you are not interested in all of these events, you will currently have to filter based on the delivered payload.

POST /your-endpoint HTTP/1.1

Host: your-host.org
Connection: close
Accept-Encoding: gzip
Content-Length: 303
Content-Type: application/json


{
  "transactionId": "28711ce3-07c4-4c8f-8577-fc8f3c4cbde0",
  "projectId": "3do82whm",
  "dataset": "production",
  "ids": {
    "created": [],
    "deleted": [],
    "updated": [
      "4f0d7277-ac0d-4bfe-ae97-dd4e2378ddaf"
    ],
    "all": [
      "4f0d7277-ac0d-4bfe-ae97-dd4e2378ddaf"
    ]
  }
}

As you will see, the delivered payloads include an object of created, updated and deleted ids. It is then up to the consumer to fetch the documents (if necessary) and trigger whichever action is wanted.

The all array contains all the touched IDs, regardless of which operations were performed. For instance, a transaction could have performed both a create and an update on the same document, in which case the array would only contain the ID once.

There are two ways of adding webhooks:

1. Using the project management console.
2. Using the Sanity CLI tool (sanity hook create)

Sanity will use the HTTP status code to determine if a delivery is successful:

• 200-range will be treated as a success
• 400-range will be treated as undeliverable, as the server said it was a client error
• 500-range will be retried using an exponential back-off pattern before giving up after 10 unsuccessful deliveries.

To see the responses from your webserver, use the CLI tool: sanity hook logs --detailed