Testing a Webhook with Localhost Endpoint using ngrok
You're correct that Sanity's servers are the ones calling your webhook endpoint, so they can't directly reach localhost. However, there are definitely ways to test webhooks during development!
The most common approach is to use a tunneling service like ngrok or similar tools (Cloudflare Tunnel, LocalTunnel, etc.) that create a public URL that forwards requests to your local development server. The Sanity documentation on GROQ-powered webhooks mentions testing webhooks, and the community commonly uses this pattern.
Here's how it typically works:
- Start your local server (e.g.,
localhost:3000) - Run ngrok:
ngrok http 3000 - Copy the public HTTPS URL ngrok provides (e.g.,
https://abc123.ngrok.io) - Use that URL as your webhook endpoint in Sanity's webhook configuration
- Requests from Sanity will now tunnel through to your localhost
Important security note: When testing webhooks, you'll want to verify the webhook signature to ensure requests are actually from Sanity. Sanity sends an X-Sanity-Signature header that you can use to verify the request authenticity using your webhook secret. This is especially important when using public tunnel URLs.
Alternative: Sanity Functions
If you're building automation or reacting to content changes, consider using Sanity Functions instead of webhooks. Functions are serverless compute that run within Sanity's infrastructure and have built-in local testing capabilities. They're event-driven, respond to content changes, and you can test them locally without any tunneling setup. Functions are generally the modern, recommended approach for content automation unless you specifically need to integrate with an external system that requires webhooks.
The GitHub repo for sanity-algolia even mentions this exact challenge: "Testing the webhook flow locally is slightly tricky as you can't point the webhook to localhost, as such you must set up a proxy to allow your local dev server..."
So yes, ngrok or similar tunneling tools are your friend for webhook testing!
Sanity – Build the way you think, not the way your CMS thinks
Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.