canonical: https://jentic.com/apis/sanity.io/sanity-webhooks

# Sanity Webhooks HTTP Endpoint

The Sanity Webhooks API sets up the webhooks that notify your services when content in a Sanity project changes, and shows how each delivery went. Document webhooks fire per document on create, update, or delete, narrowed by a GROQ filter and shaped by a GROQ projection, while transaction webhooks fire once per dataset transaction. Each webhook targets a URL and a dataset, or every dataset with *, and can set the HTTP method, custom headers, a secret, and whether drafts or all versions trigger it. Messages and delivery attempts record status, result codes, durations, and failure reasons for debugging.

## For AI agents

Create, update, disable, or delete Sanity webhooks with GROQ filters and projections, and inspect webhook messages and delivery attempts to debug failed deliveries.

## Scope

Does not receive or retry webhooks on your side, edit content, or stream changes. Use for configuring Sanity webhooks and inspecting their deliveries only.

## Capabilities

- Create a document webhook that fires on create, update, or delete for documents matching a GROQ rule.filter
- Shape the outgoing payload with a GROQ rule.projection, and set httpMethod, headers, and a secret on document webhooks
- Set up a transaction webhook that fires once per dataset transaction rather than once per document
- Pause a webhook without deleting it by setting isDisabledByUser through the update operation
- List a webhook's messages with status such as queued, sending, success, failure, transientFailure, or canceled
- Filter delivery attempts by state success or failure and read each attempt's resultCode, duration, and failureReason

## Use cases

### AI agent debugging failed webhook deliveries

When a site stops rebuilding after content edits, an agent searches Jentic for 'list failed Sanity webhook attempts', loads the listWebhookAttempts operation, and filters by state failure. It reads each attempt's resultCode, failureReason, and duration, then drills into a message's attempts to see whether the receiver is timing out or rejecting the payload, with the Sanity token injected at call time.

Example prompt: Call GET `/hooks/projects/{projectId}/{id}/attempts` for project abc123 and webhook hook_456 with state failure and limit 50, then summarize resultCode and failureReason

### Rebuild a site when content is published

A static site needs a fresh build when certain documents change. A document webhook with rule.on set to create, update, and delete, a GROQ filter such as _type == 'post', and the build hook URL triggers a rebuild for matching changes in a chosen dataset, while a projection keeps the payload to the fields the build needs.

Example prompt: POST `/hooks/projects/{projectId}` with type document, name 'Rebuild site', url https://build.example.com/hook, dataset production, apiVersion v2025-02-19, and rule {on: ['create','update','delete'], filter: "_type == 'post'"}

### Webhook housekeeping

Projects collect webhooks over time. Listing them shows each target URL and dataset, the update operation can rename a webhook, change its URL, or pause it with isDisabledByUser, and deleting removes ones that are no longer needed. Transaction webhooks reject document-only fields such as headers and secret on update.

Example prompt: Call GET `/hooks/projects/{projectId}` for project abc123, then PATCH `/hooks/projects/{projectId}/{id}` with isDisabledByUser true for any webhook pointing at a retired URL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/hooks/projects/{projectId}` | List all webhooks |
| POST | `/hooks/projects/{projectId}` | Create a document or transaction webhook |
| PATCH | `/hooks/projects/{projectId}/{id}` | Update or pause a webhook |
| DELETE | `/hooks/projects/{projectId}/{id}` | Delete a webhook |
| GET | `/hooks/projects/{projectId}/{id}/messages` | List webhook messages |
| GET | `/hooks/projects/{projectId}/{id}/attempts` | List delivery attempts |
| GET | `/hooks/projects/{projectId}/{id}/messages/{messageId}/attempts` | List attempts for one message |

## Key resources

- **Webhooks** — Document or transaction webhooks with a URL, dataset, and trigger rule
- **Messages** — Each triggered delivery, with status, payload, and failureCount
- **Attempts** — Individual delivery tries with resultCode, duration, and failureReason

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 83 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 54 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-webhooks/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Webhooks API by hand means templating the project ID and apiVersion into the host, sending a bearer token, and getting GROQ rule, projection, and apiVersion fields right on create. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Sanity puts the project ID and the webhook id in the URL path (`/hooks/projects/{projectId}/{id}`), so a rule can pin your agent to one project or a single webhook and the operations you pick. You choose the operations it may call, so destructive ones like deleteWebhook are not included unless you add them.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Sanity webhook' or 'list failed Sanity webhook attempts', and Jentic returns the matching operation, such as createWebhook or listWebhookAttempts, with its input schema.

## Related APIs

- **Sanity HTTP API** — Query and mutate the documents whose changes trigger webhooks
- **Sanity Listen API** — Stream document changes in real time instead of receiving webhooks
- **Svix API** — Send webhooks from your own application with retries and logs
- **Hookdeck API** — Receive, queue, and inspect incoming webhooks

## FAQ

### What authentication does the Sanity Webhooks API use?

Per its OpenAPI spec, the Sanity Webhooks API uses a bearer token in the Authorization header on all nine operations. Through Jentic the Sanity token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### What is the difference between document and transaction webhooks in Sanity?

A document webhook fires for every document created, updated, or deleted, so a transaction touching three documents sends three requests, and it supports GROQ filters, projections, custom headers, and a secret. A transaction webhook fires once per dataset transaction. Sanity recommends document webhooks.

### How do I see why a Sanity webhook failed?

List the webhook's attempts with state set to failure, or list its messages and then the attempts for one message. Each attempt includes resultCode, resultBody, duration, isFailure, and failureReason. The single-attempt lookup only covers transaction webhooks and returns 404 for document webhook attempts.

### What are the rate limits for the Sanity Webhooks API?

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Webhooks API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the webhook and attempt operations when it needs them.

### How do I create a Sanity webhook through Jentic?

Search Jentic for 'create a Sanity webhook', load the createWebhook operation, and execute POST `/hooks/projects/{projectId}` with type, name, url, dataset, and apiVersion, plus a rule with the events to fire on. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Webhooks API?

Yes. For a debugging agent, allow just the listWebhooks, listWebhookMessages, and listWebhookAttempts operations under project abc123. It can then trace failed deliveries for that project, but it has no route to create, change, or remove a webhook. Every call it makes is logged.
