Reliability

Reliability

Webhook delivery should be reliable even when requests are retried, arrive more than once, or temporarily fail because your system or a downstream dependency is unavailable.

Delivery Success

Jodo considers a webhook request successful when your endpoint returns a 2xx HTTP response.

The attempt is considered failed when:

• Your endpoint returns a non-2xx response.
• Your endpoint times out.
• Your endpoint is unreachable.

Design the endpoint to respond quickly. If the business workflow takes time, persist the webhook event first, return a 2xx response, and process the event asynchronously.

Retry Policy

When delivery fails, Jodo retries the webhook request. By default, Jodo retries up to 5 times, with retry attempts spaced across 6-hour and 24-hour intervals for up to 3 days.

If any retry attempt succeeds, Jodo stops retrying that event.

Idempotency

Webhook handlers must be idempotent. The same event can be delivered more than once because of retries, network timeouts, or delayed responses.

Use a stable event identifier, transaction identifier, order identifier, subscription identifier, or payment identifier to detect whether an event has already been processed.

Recommended behavior:

• Store every received event with its processing status.
• Process each unique event only once.
• If an event has already been processed, return 2xx.
• Avoid creating duplicate payments, settlements, subscriptions, or application records during retry handling.

Failure Notifications

You can configure email addresses to receive webhook failure notifications.

Failure emails include:

1. Payload
2. Response code received from your endpoint
3. Failure hint

Use these notifications to identify integration issues early, especially after deployments or infrastructure changes.

Subscription Disablement

If webhook delivery fails continuously for a configured limit, the event subscription can be disabled.

Current limits:

• Production: 100 continuous failures
• UAT: 10 continuous failures

Monitor failure alerts and resolve delivery issues before these limits are reached.

Operational Checklist

• Keep webhook endpoints highly available.
• Return 2xx only after accepting the event.
• Persist incoming payloads for audit and replay.
• Make processing idempotent.
• Log response codes and processing failures.
• Configure failure notification emails.
• Alert your team on repeated failures.