Retry & Troubleshooting
ChatYug retries failed webhook deliveries with exponential backoff for up to 48 hours. Your endpoint should respond quickly with HTTP 2xx.
Delivery settings
| Setting | Default | Environment variable |
|---|---|---|
| Automatic retry window | 48 hours | WEBHOOK_RETRY_WINDOW_HOURS |
| Maximum delivery attempts | 16 | WEBHOOK_MAX_ATTEMPTS |
| HTTP timeout per attempt | 8000 ms | WEBHOOK_DISPATCH_TIMEOUT_MS |
| Per-tenant rate limit | 300 events / minute | WEBHOOK_PER_TENANT_RPM |
| Dispatcher batch size | 50 | WEBHOOK_DISPATCH_BATCH_SIZE |
| Dispatcher poll interval | 5000 ms | WEBHOOK_DISPATCH_INTERVAL_MS |
Retry backoff schedule
After a failed attempt (non-2xx HTTP response, timeout, or network error), ChatYug schedules the next attempt using this minute-based backoff. Retries continue for up to 48 hours from when the event was first enqueued.
| After failed attempt | Wait before retry |
|---|---|
| 1 | 1 minute |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 60 minutes |
| 5+ | 360 minutes (6 hours) |
After the 48-hour window expires or all attempts are exhausted, the event is marked failed in ChatYug's delivery log.
Rate limiting
If your WABA exceeds 300 outbound webhook events per minute, additional events are deferred and retried after approximately one minute. Design your handler to be fast and idempotent.
Idempotency
Use eventId (and the X-Chatyug-Event-Id header) to deduplicate. The same event may be delivered more than once if your server returns a non-2xx status or times out after ChatYug already accepted the delivery.
Recommended handler pattern
- Verify
X-Chatyug-Signatureon the raw body (if secret configured). - Check
eventIdagainst your processed-events store; skip if already handled. - Return HTTP
200immediately. - Process the event asynchronously (queue, worker, background job).
Common issues
| Symptom | Likely cause | Fix |
|---|---|---|
| No webhooks received | URL not configured or inactive | Check Webhook Settings in portal; send a test event |
| Signature always fails | Body parsed before verify | Read raw body; see Signature Verification |
| Intermittent duplicates | Slow handler + timeout | Return 2xx within 8 seconds; process async |
| Events stop after burst | Rate limit (300/min) | Scale consumer; batch processing |
| HTTPS rejected at save | Private or local URL | Use a public HTTPS endpoint (e.g. ngrok for dev) |