Skip to main content
WEBHOOK

Balance Check Run Completed Webhook

Fires when a balance check run completes. A notification will be sent to the webhook_url specified in the /v1/balance_requests endpoint.
Important Considerations:
  • Webhook delivery is not guaranteed
  • Webhooks will be retried for up to 30 minutes with exponential backoff
  • If delivery fails after 30 minutes, no further retries will occur
  • Always implement polling as a fallback mechanism
If your webhook endpoint restricts inbound traffic by IP, make sure to allowlist Rightfoot’s outbound IPs. See IP Allowlisting.

Webhook Response

Your webhook endpoint should respond with an HTTP 2xx status code to confirm receipt:
If a 2xx response is not received, the webhook will be retried with exponential backoff for up to 30 minutes.

Implementing a Webhook Endpoint

Here are examples of implementing a webhook endpoint in various languages:

Retry Mechanism

The webhook delivery system implements exponential backoff:
  1. Initial attempt - Immediate
  2. First retry - After 1 minute
  3. Second retry - After 2 minutes
  4. Third retry - After 4 minutes
  5. Subsequent retries - Doubling interval up to 30 minutes total
After 30 minutes, no further retry attempts will be made.

Security Considerations

To secure your webhook endpoint:
  1. Use HTTPS - Always use SSL/TLS encryption for your webhook endpoint
  2. Validate payloads - Check that all required fields are present
  3. Implement idempotency - Handle duplicate webhook deliveries gracefully
  4. Add authentication - Consider implementing webhook signatures or API keys
  5. Rate limiting - Protect against potential abuse

Fallback Strategy

Since webhook delivery is not guaranteed, implement a polling fallback:

Best Practices

  1. Always implement polling - Don’t rely solely on webhooks
  2. Handle duplicates - Your system should be idempotent
  3. Log all events - Keep an audit trail of webhook receipts
  4. Monitor failures - Set up alerts for webhook processing errors
  5. Process asynchronously - Return 200 quickly and process in the background

Body

application/json
event_uuid
string
required

Unique identifier for the webhook event.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

type
string
required

The type of the webhook event, typically BALANCE_BATCH_COMPLETED.

Example:

"BALANCE_BATCH_COMPLETED"

batch_id
string
required

The ID of the batch that was processed.

Example:

"5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83"