Troubleshooting widget deployment with Netlify build hook

I can see you're experiencing a frustrating 404 error when clicking the deploy button in the sanity-plugin-dashboard-widget-netlify widget, even though your curl command to the build hook works perfectly. Let me help you troubleshoot this.

First, verify your configuration

The most common cause is incorrect configuration values. Make sure your sanity.config.ts (or .js) has the correct format:

netlifyWidget({
  sites: [
    {
      title: 'My Site',
      apiId: 'your-api-id',        // From Netlify: Site Settings > General > Site Details > API ID
      buildHookId: 'your-hook-id', // JUST the ID, not the full URL
      name: 'your-netlify-site-name',
    }
  ]
})

Critical detail about buildHookId: When you create a build hook in Netlify (Site Settings > Build & Deploy > Build Hooks), you get a URL like https://api.netlify.com/build_hooks/abc123def456. The buildHookId should be only the ID portion at the end (abc123def456), not the full URL. This is one of the most common mistakes.

Check your Netlify API ID

The apiId is found in Netlify under Site Settings > General > Site Details > Site Information > API ID. Make sure you're using this exact value, not your site name or another identifier.

Common troubleshooting steps

1. Build hook still active? - Verify that your build hook hasn't been deleted or regenerated in Netlify. If you regenerated it, you'll need to update the buildHookId in your config.

2. Check browser console - Open your browser's developer tools (F12), go to the Network tab, and click the deploy button. Look at the actual request being made and the response. This will show you the real error details, not just the "mystical 404" message the widget displays.

3. Verify site name - The name field should match your Netlify site name exactly (the part before .netlify.app in your URL).

Plugin compatibility issues

Looking at the GitHub issues for this plugin, there have been some compatibility problems with newer versions of Sanity Studio and the dashboard plugin. Make sure you're running compatible versions:

• Update to the latest version: npm install sanity-plugin-dashboard-widget-netlify@latest
• Make sure @sanity/dashboard is also up to date

Alternative approach

If the widget continues giving you trouble after trying these fixes, you might consider using Sanity Functions instead. Functions let you create serverless endpoints that can trigger your Netlify builds without the browser-based limitations. You could create a Function that calls your Netlify build hook and trigger it from a custom Studio action button. This would be more reliable since the request happens server-side.

The browser console output will be the most helpful for pinpointing the exact issue. The 404 error message from the widget itself isn't very informative, but the actual network request in the developer tools will show you exactly what's going wrong and whether it's a configuration issue or something else.