Webhooks

Webhooks enable real-time notifications about events occurring in your system. When configured events are triggered, HTTP POST requests are sent to your specified endpoint with relevant event data.

Webhook Configuration

Schema

{
  "id": "string",
  "enabled_events": ["string"],
  "mode": boolean,
  "url": "string",
  "description": "string",
  "created_at": "string"
}

Configuration Properties

Property	Type	Required	Description
`id`	string	Yes	Unique identifier for the webhook configuration
`enabled_events`	array	Yes	List of event types that trigger this webhook. Must contain at least one unique event
`mode`	boolean	Yes	Webhook operational mode. `true` for production, `false` for test mode
`url`	string	Yes	HTTPS endpoint URL where webhook payloads will be delivered
`description`	string	Yes	Human-readable description of the webhook's purpose
`created_at`	string	Yes	ISO 8601 timestamp indicating when the webhook was created

Supported Events

Client Status Updated

Event: client_status_updated

Triggered when a client's status changes (e.g., active, suspended, terminated).

Payload Structure:

{
  "event_type": "client_status_updated",
  "event_id": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "client_id": "cli_abc123",
    "previous_status": "active",
    "current_status": "pending",
    "reason": "needs_information",
  }
}

Credit Status Updated

Event: credit_status_updated

Triggered when a client's credit status or limit changes.

Payload Structure:

{
  "event_type": "credit_status_updated",
  "event_id": "evt_0987654321",
  "timestamp": "2024-01-15T11:45:00Z",
  "data": {
    "client_id": "cli_abc123",
    "credit_limit": {
      "previous": 5000.00,
      "current": 7500.00,
      "currency": "USD"
    },
    "credit_used": 2500.00,
    "credit_available": 5000.00,
    "status": "approved",
    "reason": "manual_adjustment",
  }
}

Common Webhook Payload Structure

All webhook events follow a consistent structure:

{
  "event_type": "string",
  "event_id": "string",
  "timestamp": "ISO 8601",
  "data": {
    // Event-specific data
  }
}

Standard Fields

event_type: The type of event that triggered the webhook

event_id: Unique identifier for this specific event occurrence

timestamp: ISO 8601 formatted timestamp of when the event occurred

webhook_id: ID of the webhook configuration that triggered this delivery

data: Event-specific payload containing relevant information

Webhook Security

Signature Verification

Each webhook request includes a signature header for verification:

X-Webhook-Signature: sha256=<signature>

The signature is computed using HMAC-SHA256 with your webhook secret and the raw request body.

Verification Example

Delivery Behavior

Retry Policy

Failed webhook deliveries (non-2xx responses) are retried up to 5 times

Retry intervals: 1 min, 5 min, 30 min, 2 hours, 12 hours

Webhooks timing out after 30 seconds are considered failed

Response Requirements

Your endpoint should:

Return a 2xx status code to acknowledge receipt

Respond within 30 seconds

Process webhooks asynchronously to avoid timeouts

Webhook Configuration#

Schema#

Configuration Properties#

Supported Events#

Client Status Updated#

Credit Status Updated#

Common Webhook Payload Structure#

Standard Fields#

Webhook Security#

Signature Verification#

Verification Example#

Delivery Behavior#

Retry Policy#

Response Requirements#