Webhook Delivery: Retries, Timeouts & Debugging

Overview

This page covers the delivery mechanics of the core system's webhook events: when a failed delivery gets retried, how long your server has to respond, and how to debug delivery problems. It does not cover event payload structure or event types (see Webhooks & Events) or how to verify a request genuinely came from the core system (see Webhook Signature Verification & Security).

Whether a webhook delivery is retried depends entirely on the HTTP status code your server returns:

In other words, only 5xx responses are treated as retryable failures. A 4xx response is treated as a deliberate rejection of that event and will not be retried, so make sure your handler only returns a 4xx when the event genuinely should not be reprocessed.

Your webhook handler needs to respond within 10 seconds. If verification and processing together would take longer than that, you'll see timeout errors on the delivery.

The recommended pattern is to queue heavy work and respond immediately, rather than blocking the response on downstream processing:

// Good: quick response, async processing
app.post('/webhook', async (req, res) => {
  // Queue the work instead of blocking on it
  await queue.add('process-webhook', req.body);
  res.status(200).send();
});

If you're also verifying a signature (see Webhook Signature Verification & Security), verify first, then queue the heavy work and acknowledge with a 200 — don't make the core system wait on a slow downstream call before you've even confirmed the request is legitimate.

When you use the core system's CLI listener to forward webhook events to your local development server, it adds extra headers to each forwarded request for debugging purposes:

X-Forwarded-For: core-system-webhook-listener
X-Original-Host: <your-tunnel-domain>
X-Webhook-Event: call-started
X-Webhook-Timestamp: 1705331445

Your server receives the exact webhook payload alongside these additional headers, which makes it easier to confirm which event triggered a given request and when it was sent. Remember the CLI listener is a forwarder only — it does not create a public URL itself, so you still need a separate tunneling service pointed at it during local development (see Webhooks & Events for the full local-testing setup).

For production debugging, use Observe > Webhook Logs in the Sulus dashboard to:

• Verify webhook deliveries reached your server
• Check server response codes and delivery timing
• Debug authentication/signature issues
• Monitor event delivery failures over time

Common delivery issues and where to look:

In short: 5xx responses get retried, 4xx and 2xx responses do not, your handler must respond within 10 seconds (queue anything heavier), and Observe > Webhook Logs in the dashboard is your primary tool for confirming deliveries and diagnosing failures. For event types and payload structure, see Webhooks & Events; for verifying requests are authentic, see Webhook Signature Verification & Security.