Retry Mechanism

SCALAR implements automatic retry logic for failed webhook deliveries to ensure reliability:

Retry Strategy:

• Initial Attempt: Immediate delivery attempt
• Retry Attempts: Up to 5 retries with exponential backoff
• Backoff Schedule:
  • Retry 1: Immediate
  • Retry 2: 5 seconds
  • Retry 3: 30 seconds
  • Retry 4: 5 minutes
  • Retry 5: 30 minutes

Retryable Errors:

• HTTP 5xx Server Errors (500, 502, 503, 504)
• Connection timeouts
• DNS resolution failures
• Network connection errors
• Customer Webhook Endpoint is not reachable

Non-Retryable Errors:

• HTTP 400 Bad Request - Check your payload format
• HTTP 401 Unauthorized - Verify authentication credentials
• HTTP 403 Forbidden - Verify endpoint permissions
• HTTP 404 Not Found - Verify webhook URL is correct
• Invalid certificate errors - Update your SSL/TLS certificate

Handling High-Volume Delivery Issues

Overflow Behavior:

When SCALAR detects that your webhook is not accepting data (repeated failures), it may:

1. Put the subscription on "onHold” status after all 5 retries
2. Buffer incoming events for up to 7 days
3. Stop accepting new events after 7 days of non-delivery
4. Your webhook will receive only last 24 hours data

Recovery Steps:

1. Fix the issue with your webhook endpoint
2. Verify endpoint is responding with 200 status code
3. Ensure server capacity can handle the load
4. Increase batch size or linger time if needed
5. Reactivate the subscription from the dashboard

Common Error Scenarios

Scenario 1: Webhook Endpoint Timeout

Your endpoint takes longer than 3-5 seconds to respond:

Solution:

• Implement asynchronous processing - return 200 immediately, process events in background
• Optimize database queries and external API calls
• Scale server resources to handle load
• Increase response timeout if your system genuinely needs more time

Scenario 2: Certificate Validation Failures

SCALAR cannot verify your SSL certificate:

Solution:

• Ensure SSL certificate is valid and not expired
• Use a certificate from a trusted Certificate Authority
• Check that your domain matches the certificate
• Update certificate chain if needed

Scenario 3: IP Address Blocked

Your firewall is rejecting SCALAR's requests:

Solution:

• Whitelist SCALAR's IP addresses (see section on IP Whitelisting)
• Verify firewall rules allow HTTPS (port 443)
• Check network ACLs and security groups
• Contact your infrastructure team to review access logs

Scenario 4: HMAC Signature Validation Fails

Your endpoint rejects requests due to signature mismatch:

Solution:

• Verify you're using the correct webhook secret
• Ensure you're validating against the correct header (X-Webhook-Signature)
• Use proper HMAC-SHA256 validation algorithm
• Check for character encoding issues