Webhook Troubleshooting

If you're not receiving webhooks, use this checklist to diagnose and fix common issues. Before contacting support, confirm each of the following:

Troubleshooting Checklist

Endpoint Returns 200 OK

Your webhook endpoint must return HTTP status code 200 OK to acknowledge successful receipt of the webhook. Any other status code (including other 2xx codes like 201 Created or 204 No Content) will be treated as a failure and trigger retries.

Common Issues:

• Returning 201 Created instead of 200 OK
• Returning 204 No Content (empty body)
• Throwing unhandled exceptions that result in 500 Internal Server Error
• Authentication failures returning 401 Unauthorized or 403 Forbidden

Solution: Ensure your endpoint explicitly returns 200 OK with a response body (even if empty JSON {}).

HTTPS (Not HTTP)

Webhooks are only delivered over HTTPS. HTTP endpoints are not supported for security reasons.

Common Issues:

• Using http:// instead of https:// in your webhook URL
• Self-signed certificates that fail validation
• Expired SSL certificates

Solution: Use a valid HTTPS URL with a properly configured SSL certificate.

No Auth Blocking

If your endpoint requires authentication, ensure it's configured correctly and not blocking webhook requests.

Common Issues:

• API keys or tokens not configured in webhook URL
• IP whitelisting blocking Stash servers
• Basic auth or OAuth failing
• Rate limiting blocking webhook requests

Solution:

• If using query parameters for auth: https://your-endpoint.com/webhook?api_key=xxx
• If using headers: Configure your endpoint to accept authentication via headers (note: Stash doesn't send custom auth headers by default)
• Whitelist Stash IP ranges if using IP-based restrictions
• Ensure rate limits allow webhook traffic

Correct Environment (Test/Prod)

Ensure you're checking the correct environment for webhook deliveries.

Common Issues:

• Testing in production but webhook configured for test environment
• Webhook endpoint pointing to localhost or internal network
• Environment-specific webhook URLs not properly configured

Solution: Verify your webhook endpoint URL matches the environment you're testing in.

Signature Verification Disabled/Enabled Intentionally

Signature verification is optional but recommended for security. If enabled, ensure your endpoint correctly verifies the HMAC signature.

Common Issues:

• Signature verification enabled but secret not configured correctly
• Signature verification disabled when it should be enabled (security risk)
• Incorrect signature verification logic

Solution: See the Signature Verification section in the webhook listener guide.

Why am I not receiving events?

If you've checked all items in the troubleshooting checklist above and still aren't receiving webhooks, consider the following:

Event Subscription

Ensure you've subscribed to the specific events you need. Not all events are enabled by default. Check your webhook configuration in Stash Studio to confirm which events are active.

Webhook Delivery Status

Check the webhook delivery logs in Stash Studio to see:

• Whether webhooks are being sent
• What response codes your endpoint is returning
• Any error messages from failed deliveries

Network and Firewall Issues

Testing Your Endpoint

You can test your webhook endpoint manually to verify it's working:

1. Use a webhook testing tool: Services like webhook.site or ngrok can help you test webhook delivery
2. Send a test request: Use curl or Postman to send a test payload to your endpoint
3. Check logs: Monitor your server logs to see if requests are reaching your endpoint

Common Signature Verification Issues

Signature Mismatch

If signature verification is failing, check:

1. Secret key: Ensure you're using the correct webhook secret from Stash Studio
2. Raw body: Use the exact raw request body (don't parse and re-serialize JSON)
3. Encoding: The secret is Base64 encoded - ensure you're handling this correctly
4. Header name: The signature is in the Stash-Hmac-Signature header (not stash-hmac-signature)

Signature Verification Disabled

If you choose to disable signature verification for testing, ensure you re-enable it before going to production.

Still Having Issues?

If you've gone through this checklist and are still experiencing problems:

1. Check Stash Studio logs: Review webhook delivery attempts and error messages
2. Review server logs: Check your backend logs for incoming requests and errors
3. Test endpoint manually: Verify your endpoint responds correctly to test requests
4. Contact support: Provide details about:
   • Your webhook endpoint URL
   • The events you're subscribed to
   • Any error messages from logs
   • Steps you've already taken to troubleshoot