> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sanity Webhook Setup Guide

> Configure Sanity to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/sanity#getting-started) on the Sanity connector page.

<section data-guide-section data-guide-scopes="">
  <h2>How webhooks are set up</h2>

  <p>StackOne creates and manages the webhook subscription automatically when the account is connected. StackOne creates one GROQ-powered document webhook named `StackOne` in your Sanity project that covers all datasets and exactly the events you enable, and deletes it when the account is disconnected. There is nothing to configure in Sanity.</p>

  <ul>
    <li>Connect with a project API token that includes <strong>Blueprints Deployer</strong> (sanity.io/manage > your project > <strong>API</strong> > <strong>Tokens</strong> > <strong>Add API token</strong> > <strong>Permissions</strong> > <strong>Other roles</strong>). <strong>Blueprints Deployer</strong> alone is enough to create and delete the webhook; add <strong>Editor</strong> and <strong>Access Manager</strong> only if the same connection also runs document or access-management actions.</li>
    <li>The webhook appears in sanity.io/manage under your project > <strong>API</strong> > <strong>Webhooks</strong> as `StackOne`. Do not edit or delete it — changing its URL, dataset, or triggers stops event delivery.</li>
    <li>Draft (`drafts.`) and release version (`versions.`) documents are ignored — only changes to published documents fire events.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Sanity events can be enabled. Only events selected in StackOne are included in the webhook triggers — Sanity does not deliver events that are not subscribed.</p>

  <Steps>
    <Step title="Document events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired when published documents change in any dataset of the project.</p>

        <ul>
          <li><strong>Document Created</strong> (`create`) — Fired when a new published document is created.</li>
          <li><strong>Document Updated</strong> (`update`) — Fired on every change to an existing published document.</li>
          <li><strong>Document Deleted</strong> (`delete`) — Fired when a published document is deleted or unpublished.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Sanity delivers events to StackOne.</p>

  <Steps>
    <Step title="One request per document">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sanity sends one JSON POST per changed document, even when a single transaction changes several documents. The body contains `_id`, `_type`, `_rev`, `operation`, and the document `before` and `after` the change (`before` is null on create, `after` is null on delete).</p>
      </div>
    </Step>

    <Step title="Operation headers">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each delivery carries the `sanity-operation` header (`create`, `update`, or `delete`), which StackOne uses to route the event, plus `sanity-document-id`, `sanity-dataset`, `sanity-transaction-id`, `sanity-transaction-time`, and an `idempotency-key` for de-duplicating retries.</p>
      </div>
    </Step>

    <Step title="Retries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sanity retries a failed delivery twice, 30 seconds apart, on timeouts, `429`, and `5xx` responses. StackOne responds with `200 OK` automatically.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.