Webhook Troubleshooting

Debug webhook delivery issues and common problems.

Viewing Delivery Logs

Check webhook delivery history in Settings → Integrations → Webhooks:

  1. Click on a webhook
  2. Click Logs to view recent deliveries
  3. Each delivery shows status, response code, and timing

Common Issues

1. Webhook Not Receiving Events

Symptoms: No deliveries appearing in logs

Causes:

  • Webhook is disabled
  • No events subscribed
  • Events not occurring

Solutions:

  • Check webhook is Active in settings
  • Verify events are selected (e.g., ticket.created)
  • Use the Test button to send a sample event

2. Delivery Failures (4xx/5xx)

Symptoms: Deliveries show failed status

401 Unauthorized

Your endpoint requires authentication. Either:

  • Remove auth requirement for the webhook endpoint
  • Whitelist cStar's IP addresses
  • Add auth token to your endpoint URL

403 Forbidden

Your server is blocking the request:

  • Check firewall rules
  • Verify the endpoint path is correct
  • Ensure CORS isn't blocking POST requests

404 Not Found

The webhook URL is incorrect:

  • Verify the URL in webhook settings
  • Check your server routing configuration

500 Server Error

Your endpoint crashed:

  • Check your server logs
  • Ensure your handler doesn't throw exceptions
  • Verify JSON parsing is working

3. Timeouts

Symptoms: Deliveries timing out (30s limit)

Solutions:

  • Return 200 OK immediately
  • Process the webhook asynchronously
  • Queue the payload for later processing
// Bad: Synchronous processing
app.post('/webhook', async (req, res) => {
  await processTicket(req.body); // May take > 30s
  res.sendStatus(200);
});

// Good: Async processing
app.post('/webhook', (req, res) => {
  res.sendStatus(200); // Return immediately
  queue.add(req.body); // Process later
});

4. Signature Verification Failing

Symptoms: Your code rejects valid webhooks

Causes:

  • Wrong secret
  • JSON serialization mismatch
  • Encoding issues

Solutions:

  1. Verify you're using the correct secret
  2. Use raw request body for signature computation
  3. Don't modify the payload before verification
// Use raw body for verification
app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-signature'];
    const rawBody = req.body.toString();
    // Verify using rawBody, not parsed JSON
  }
);

5. Auto-Disabled Webhook

Symptoms: Webhook shows "Auto-disabled" status

Cause: 5 consecutive delivery failures

Solution:

  1. Fix the underlying issue (check logs)
  2. Click Enable to reactivate
  3. Send a test to verify it's working

Retry Behavior

Failed deliveries are automatically retried:

Attempt Delay
1 Immediate
2 1 minute
3 5 minutes
4 30 minutes
5 2 hours
6 6 hours
7 24 hours (final)

After 5 consecutive failures, the webhook is auto-disabled.

Testing Tips

  1. Use the Test button - Sends sample events without waiting for real data
  2. Check response times - Aim for < 1 second responses
  3. Monitor error rates - High failure rates indicate problems
  4. Use webhook.site - Great for debugging payload structure

Debug Checklist

  • Webhook is enabled/active
  • Events are subscribed
  • URL is correct and accessible
  • Server returns 200 within 30 seconds
  • Signature verification uses correct secret
  • No firewall blocking cStar IPs

Getting Help

If issues persist:

  1. Check the delivery logs for specific errors
  2. Review your server logs
  3. Contact support with your webhook ID and error details

Related