Webhooks not working? This page covers every common failure mode and how to fix it.

Checking Delivery Logs

First step for any webhook issue: check the logs.

  1. Go to Settings → Team → Webhooks.
  2. Click the webhook in question.
  3. Click Logs to see recent deliveries.

Each delivery shows the HTTP status, response time, request and response headers, and body. Most problems are diagnosable from the logs alone.

How retries work

Failed deliveries don't disappear. cStar retries up to 6 times with exponential backoff: 30s, 2m, 10m, 1h, 6h, 24h. Anything other than a 2xx response counts as a failure (timeouts and network errors included).

This means a flaky endpoint that recovers within a day can self-heal without you doing anything. It also means a misconfigured endpoint will keep getting hammered until you fix it or the retries exhaust.

No Deliveries Appearing

If the logs are empty:

  • Is the webhook active? Check that it's toggled on.
  • Are events subscribed? A webhook with no events selected won't fire.
  • Did the event actually happen? Use the Test button to send a sample event and confirm your endpoint is reachable.

HTTP Error Responses

401 Unauthorized

Your endpoint requires authentication that the webhook request doesn't provide.

Fixes:

  • Remove auth requirements from the webhook endpoint and use signature verification instead (see Webhook Security)
  • Whitelist the User-Agent: cStar-Webhooks/1.0 header at your WAF
  • If you must include a token, never put it in the URL. Use a custom header so it doesn't leak via referrer or proxy logs.

403 Forbidden

Your server or firewall is rejecting the request. Most common cause is a WAF (Cloudflare, AWS WAF) blocking the cStar-Webhooks/1.0 user agent.

Fixes:

  • Allow cStar-Webhooks/1.0 in your WAF rules
  • Verify the endpoint path and method (must accept POST)
  • CORS doesn't apply here. Webhooks are server-to-server, not browser requests.

404 Not Found

The URL is wrong.

Fixes:

  • Double-check the URL in webhook settings
  • Verify your server's routing configuration
  • Make sure the endpoint is actually deployed (not just running on localhost)

500 Internal Server Error

Your endpoint is crashing when it receives the payload.

Fixes:

  • Check your server logs for the stack trace
  • Wrap your handler in try/catch
  • Make sure you're parsing JSON correctly

Timeouts

cStar waits 10 seconds for a response. If your endpoint doesn't respond in time, the delivery is marked as failed and queued for retry.

The fix is almost always the same: return 200 OK immediately and process the webhook asynchronously.

// Return fast, process later
app.post('/webhook', (req, res) => {
  res.sendStatus(200);
  queue.add('process-webhook', req.body);
});

"URL validation failed" or "Could not connect"

cStar refuses to deliver to private network addresses to prevent SSRF. If your URL points at any of these, deliveries will fail before they even leave our servers:

  • localhost or 127.0.0.0/8
  • RFC 1918 private ranges (10.x, 172.16-31.x, 192.168.x)
  • Link-local (169.254.x)
  • *.local, *.internal, *.lan

Use a public URL. For local development, tunnel your server with ngrok, Cloudflare Tunnel, or Tailscale Funnel.

Signature Verification Failing

If your verification code rejects valid webhooks:

  1. Right format? Current deliveries use Stripe-style X-Signature: t=<unix>,v1=<hex>. If your verifier is matching sha256=<hex>, that's the legacy format and only matches older deliveries. Update to the parser shown in Webhook Security.
  2. Right secret? Each webhook has its own secret. Easy to mix them up.
  3. Verifying the raw body? Parsing JSON and re-serializing it changes key order or whitespace. Always verify against the raw request body string.
  4. HMAC input correct? For Stripe-style, the HMAC is computed over ${t}.${rawBody}, not just rawBody.
  5. Clock skew? The 5-minute replay window will reject signatures whose t= value is too far from your server's clock. Sync via NTP.
  6. Encoding? Make sure body and secret are both treated as UTF-8.
// Correct: use raw body, parse t= and v1= from the header
app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString();
    const isValid = verifyWebhook(rawBody, req.headers['x-signature'], SECRET);
    // ...
  }
);

Auto-Disabled Webhooks

After 10 consecutive delivery failures, cStar marks the webhook auto-disabled. You'll see an "Auto-disabled" status badge in the settings.

Each delivery already burns its own 6-attempt retry curve (30s, 2m, 10m, 1h, 6h, 24h), so 10 consecutive failures means the endpoint has been broken for ~3 days minimum. At that point we stop wasting retries.

To recover:

  1. Fix the underlying problem (check the last few delivery logs for clues).
  2. Click Enable to reactivate.
  3. Send a test event to verify it's working.
  4. The failure counter resets on the next successful delivery.

Quick Diagnostic Checklist

  • Webhook is enabled and active
  • At least one event type is subscribed
  • URL is correct, publicly accessible, not on a private network
  • Server returns 200 within 10 seconds
  • Signature verification uses the correct secret and the raw body
  • No firewall or WAF blocking cStar-Webhooks/1.0
  • Endpoint handles POST

Still Stuck?

  1. Review the delivery logs. They include request and response details.
  2. Check your server logs for errors.
  3. Try https://webhook.site to test payload structure in isolation.
  4. Contact support with your webhook ID and a description of the issue.

Related