Define a webhook with Blueprints

Blueprints let you define and manage your webhooks in code, then deploy them in a predictable manner.

With webhooks, you can send customized HTTP requests when documents in your Content Lake change. If you also need code to run when documents change, use Functions.

In this guide, you’ll define a webhook resource with Blueprints and deploy the blueprint to Sanity.

Prerequisites:

• The latest version of the sanity CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with npx sanity@latest.
• An existing project and a role with permission to edit webhooks (requires the sanity-project-webhooks permission).
• Version 0.11.0 or later of the @sanity/blueprints library. We recommend using the latest version.

npx sanity@latest blueprints init . --type ts --project-id YOUR_PROJECT_ID --stack-name production

pnpm dlx sanity@latest blueprints init . --type ts --project-id YOUR_PROJECT_ID --stack-name production

yarn dlx sanity@latest blueprints init . --type ts --project-id YOUR_PROJECT_ID --stack-name production

bunx sanity@latest blueprints init . --type ts --project-id YOUR_PROJECT_ID --stack-name production

Add the defineDocumentWebhook helper to your sanity.blueprint.ts configuration to define a webhook:

import { defineBlueprint, defineDocumentWebhook } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineDocumentWebhook({
      name: 'my-webhook',
      on: ['create'],
      url: 'https://example.com/webhook',
      filter: '_type == "post"',
      projection: '{_id}',
      dataset: 'production',
      apiVersion: 'v2026-01-01',
    })
  ],
})

The dataset and apiVersion fields are required. Set apiVersion to a date in the format vYYYY-MM-DD, including the leading v. Webhooks you create in your project settings default to API version v2021-03-25, but a webhook defined in a blueprint has no default, so you must set it.

For a full list of configuration options, see the reference documentation.

After you’ve configured your webhook, deploy the blueprint:

npx sanity blueprints deploy

pnpm dlx sanity blueprints deploy

yarn dlx sanity blueprints deploy

bunx sanity blueprints deploy

After the deployment finishes, your webhook begins sending updates whenever a document that matches the configuration changes.

To confirm that the webhook was created, run npx sanity hooks list. It lists each webhook in your project with its name, dataset, and URL. If deliveries fail, open the webhook's attempts log from its menu in your project settings at sanity.io/manage. For more help, see debugging GROQ-powered webhooks.

If you need to make changes, update the blueprint file (sanity.blueprint.ts) and run the deploy command again.

Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.

To remove a resources created with a blueprint, you need to either:

• Remove the definition from the blueprint, and run the deploy command again.
• Destroy the blueprint with the destroy command.

The blueprints destroy command removes, or undeploys, the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.

npx sanity blueprints destroy

pnpm dlx sanity blueprints destroy

yarn dlx sanity blueprints destroy

bunx sanity blueprints destroy

To remove the resource from the blueprint locally, you can remove it from the resources array in the sanity.blueprint.ts file, then delete any associated files.

When you run blueprints destroy, it's as if you never used blueprints init during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:

npx sanity blueprints init

pnpm dlx sanity blueprints init

yarn dlx sanity blueprints init

bunx sanity blueprints init

This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.