Skip to main content
WEBHOOK
balance_threshold_alert
{
  "event_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "type": "BALANCE_THRESHOLD_ALERT",
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "batch_id": "987fcdeb-51a2-3bc4-d567-890123456789",
  "alerts": [
    {
      "authorizer_unique_id": "user-123",
      "balance": 150,
      "threshold_amount": 100
    },
    {
      "authorizer_unique_id": "user-456",
      "balance": 250.5,
      "threshold_amount": 200
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

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

Payload Structure

{
  "event_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "type": "BALANCE_THRESHOLD_ALERT",
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "batch_id": "987fcdeb-51a2-3bc4-d567-890123456789",
  "alerts": [
    {
      "authorizer_unique_id": "user-123",
      "balance": 150.00,
      "threshold_amount": 100.00
    },
    {
      "authorizer_unique_id": "user-456",
      "balance": 250.50,
      "threshold_amount": 200.00
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Payload Fields

FieldTypeDescription
event_uuidstringUnique identifier for this webhook event
typestringAlways BALANCE_THRESHOLD_ALERT for this event type
schedule_idstringThe monitoring schedule that triggered the alert
batch_idstringThe batch ID for this balance check run
alertsarrayList of authorizers that met or exceeded their threshold
alerts[].authorizer_unique_idstringYour unique identifier for the authorizer
alerts[].balancenumberThe authorizer’s current balance in dollars
alerts[].threshold_amountnumberThe configured threshold in dollars
timestampstringISO 8601 timestamp when the event was created

Webhook Response

Your webhook endpoint should respond with an HTTP 2xx status code to confirm receipt:
{
  "status": "received"
}
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:
from flask import Flask, request, jsonify
import logging

app = Flask(__name__)

@app.route('/webhook/threshold-alert', methods=['POST'])
def handle_threshold_alert():
    try:
        # Parse the webhook payload
        data = request.get_json()

        # Validate required fields
        if not all(k in data for k in ['event_uuid', 'type', 'batch_id', 'alerts']):
            return jsonify({'error': 'Missing required fields'}), 400

        # Verify the event type
        if data['type'] != 'BALANCE_THRESHOLD_ALERT':
            return jsonify({'error': 'Unexpected event type'}), 400

        # Process each alert
        for alert in data['alerts']:
            logging.info(
                f"Threshold met: {alert['authorizer_unique_id']} "
                f"has ${alert['balance']} (threshold: ${alert['threshold_amount']})"
            )
            # Take action - initiate payment, send notification, etc.
            process_threshold_alert(alert)

        # Return success response
        return jsonify({'status': 'received'}), 200

    except Exception as e:
        logging.error(f"Webhook processing error: {str(e)}")
        return jsonify({'error': 'Internal server error'}), 500

def process_threshold_alert(alert):
    # Initiate payment collection
    # Update your database
    # Send notifications
    pass

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"