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.

Error Handling & Retries

Retry Logic

When a webhook delivery fails, finlight automatically retries the request on a fixed, backed-off schedule:

Retry Schedule:

• 1st retry: 10 minutes after the failed attempt
• 2nd retry: 30 minutes after the 1st retry fails
• 3rd retry: 60 minutes after the 2nd retry fails

Maximum Attempts:

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

What Triggers Retries

Retries occur for:

• Any non-2xx HTTP response — including 3xx redirects, which are not followed
• 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)
• HTTP 410 Gone — this disables the webhook immediately (see below)
• Invalid webhook configuration (malformed URLs)
• Disabled webhooks

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 attempt increases the count — retries count individually, so a single event that exhausts all 4 attempts adds 4 to the counter
3. Auto-Disable at 10 - After 10 failed attempts with no success in between, the webhook is automatically disabled

The counter itself expires after 7 days without a failure, so an endpoint that fails occasionally but never 10 times in a streak is never auto-disabled.

Auto-Disable Behavior

When Auto-Disable Triggers:

• 10 failed delivery attempts with no successful delivery in between (retries count individually)
• A single HTTP 410 Gone response — disables immediately, with no retries (see below)
• Webhook status changes from "enabled" to "disabled"
• No further webhook attempts until manually re-enabled

How you are notified:

• We send you an email (typically within ~10 minutes of the webhook being disabled)
• There is no in-app notification — in the dashboard, the webhook simply shows as Disabled, and its detail page explains why

Important Notes:

• Only failures with no success in between 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, non-2xx responses, connection and TLS errors)

HTTP 410 Gone — immediate disable

If your endpoint answers a delivery with HTTP 410 Gone, finlight treats that as "this endpoint is permanently gone": the webhook is disabled straight away, with no retries and without waiting for the failure counter to reach 10. Return 410 deliberately when you want to shut a webhook off from your side; return 5xx if you want the delivery retried instead.

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

10 failed attempts, no success in between (counter = 10)
→ Webhook automatically disabled

Note: these are attempts, not events. Retries count too, so ~3 events
that each fail all 4 attempts are enough to reach 10.

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 the webhook — press Enable on its detail page in the dashboard
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

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

What doesn't count:

• Test webhook requests sent from the dashboard - these do not consume your delivery quota. They are separately rate-limited (a handful per minute).

Quota Impact Example:

1 webhook event that fails all 4 attempts = 4 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

Running out of quota pauses deliveries — it does not disable the webhook

This is an important distinction, because the two states look different in the dashboard:

• Auto-disabled (delivery failures): the webhook's status becomes Disabled. You re-enable it yourself once the endpoint is fixed.
• Quota exhausted: the webhook's status stays Enabled, but every delivery is silently paused — no events reach your endpoint, and matching articles are skipped rather than queued.

When your webhook quota runs out we send you an email, and the webhook's detail page in the dashboard shows a banner explaining that deliveries are paused. Deliveries resume when your quota resets, or immediately if you upgrade your plan.

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.