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:

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

• Webhooks Overview
• Webhook Security
• Error Codes Reference