Good to Know - Webhook Limitations & System Behavior

Understanding how finlight handles webhook errors, retries, and limitations helps you build more reliable integrations and manage your quota effectively.

RETRIESSystem Behavior

Error Handling & Retries

Retry Logic

When a webhook delivery fails, finlight automatically retries the request:

Retry Schedule:

  • 1st retry: Immediately after initial failure
  • 2nd retry
  • 3rd retry

Maximum Attempts:

  • Total of 3 delivery attempts per webhook event
  • Each retry uses the same payload and headers
  • All retry attempts are logged in your call history

What Triggers Retries

Retries occur for:

  • HTTP error codes 4xx and 5xx responses
  • Network timeouts (5 second limit)
  • Connection failures (DNS errors, refused connections)
  • SSL/TLS errors (certificate issues)

What Doesn't Trigger Retries

No retries for:

  • HTTP 2xx responses (considered successful)
  • Invalid webhook configuration (malformed URLs)
  • Disabled webhooks
AUTO_DISABLEFailure Protection

Auto-Disable Protection

Consecutive Failure Tracking

finlight tracks consecutive webhook failures to protect your quota and prevent endless failed attempts.

How It Works:

  1. Success Resets Counter - Any successful delivery (HTTP 2xx) resets the failure counter to 0
  2. Failures Increment Counter - Each failed delivery increases the consecutive failure count
  3. Auto-Disable at 10 - After 10 consecutive failures, the webhook is automatically disabled

Auto-Disable Behavior

When Auto-Disable Triggers:

  • 10 consecutive failed deliveries across all retry attempts
  • Webhook status changes from "enabled" to "disabled"
  • Dashboard notification appears indicating auto-disable
  • No further webhook attempts until manually re-enabled

Important Notes:

  • Only consecutive failures count toward auto-disable
  • Any successful delivery resets the counter to 0
  • Manual re-enabling required - webhooks don't auto-enable
  • All failure types count (timeouts, 4xx, 5xx responses)

Example Scenarios

Scenario 1: Counter Reset

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

Scenario 2: Auto-Disable

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled
RECOVERYGetting Back Online

Recovery & Re-enabling

Manual Re-enabling Process

Steps to Re-enable:

  1. Identify root cause using call history
  2. Fix endpoint issues (authentication, URL, server errors)
  3. Re-enable webhook in webhook detail by editing status setting
  4. Test webhook manually using dashboard test button
  5. Monitor initial deliveries to confirm resolution

Prevention Strategies

Avoid Auto-Disable:

  • Implement proper error handling in your endpoint
  • Return appropriate HTTP status codes
  • Monitor webhook health proactively
  • Set up alerting for webhook failures
  • Test changes in development before production
QUOTAUsage Tracking

Quota Management

You can view your usage on the dashboard on the graph. Keep in mind the usage is recorded delayed.

Failed Requests Count Toward Quota

Important: All webhook delivery attempts count toward your subscription quota, including failed deliveries.

What Counts:

  • Initial delivery attempts - count toward quota
  • All retry attempts - each retry counts separately
  • Failed deliveries - still consume quota
  • Test webhook requests - also count toward quota

Quota Impact Example:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

Managing Quota Efficiently

Best Practices:

  • Fix endpoint issues quickly to minimize failed retries
  • Monitor call history for failure patterns
  • Test thoroughly before enabling webhooks in production
  • Use proper error handling to return appropriate status codes

Quota Protection: The auto-disable feature helps prevent quota waste by stopping deliveries to consistently failing endpoints.

For webhook setup guidance, see the main webhooks documentation. For testing and debugging, check the testing guide.