Retry & Troubleshooting
ChatYug retries failed webhook deliveries with exponential backoff. Your endpoint should respond quickly with HTTP 2xx.
Delivery settings
| Setting | Default | Environment variable |
|---|---|---|
| Maximum delivery attempts | 8 | 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:
| Attempt | Wait before retry |
|---|---|
| 1 | 1 minute |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 60 minutes |
| 5+ | 180 minutes |
After 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) |
Test your endpoint: Use "Send test event" in Webhook Settings to validate URL, TLS, and signature handling before going live.