Skip to main content
WEBHOOK

Balance Threshold Alert Webhook

When a scheduled balance check finds authorizers whose balance meets or exceeds their configured threshold, a notification is sent to the webhook URL specified when creating the monitoring schedule.
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.

Payload Structure

Payload Fields

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 to handle threshold alerts:

Best Practices

  1. Act on alerts promptly - Threshold alerts indicate optimal payment timing
  2. Handle duplicates - Your system should be idempotent
  3. Log all events - Keep an audit trail of threshold alerts
  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:

"550e8400-e29b-41d4-a716-446655440000"

type
string
required

The type of the webhook event, always BALANCE_THRESHOLD_ALERT for this event.

Example:

"BALANCE_THRESHOLD_ALERT"

schedule_id
string
required

The ID of the monitoring schedule that triggered the alert.

Example:

"123e4567-e89b-12d3-a456-426614174000"

batch_id
string
required

The batch ID for this balance check run.

Example:

"987fcdeb-51a2-3bc4-d567-890123456789"

alerts
object[]
required

List of authorizers that met or exceeded their configured threshold.

timestamp
string<date-time>
required

ISO 8601 timestamp when the event was created.

Example:

"2024-01-15T10:30:00Z"