Webhooks

Webhooks allow you to receive real-time notifications about events happening in your Maraboo account. This guide explains how to set up, secure, and handle webhooks effectively.

What are Webhooks?

Webhooks are HTTP callbacks that Maraboo sends to your server when specific events occur. Instead of constantly polling the API to check for updates, Maraboo pushes notifications to you in real-time.

Benefits of Webhooks

• ⚡ Real-time notifications - Receive updates instantly as events occur
• 🔄 Reduced API calls - No need to poll for status updates
• 💰 Cost-effective - Saves on API rate limits and infrastructure
• 🎯 Event-driven architecture - Build reactive applications
• 📊 Better user experience - Provide instant feedback to users

Common Use Cases

• Transaction notifications - Know immediately when a payment completes
• Wallet updates - Track balance changes and wallet events
• Status changes - Monitor transaction status transitions
• Failed operations - Get notified of errors requiring attention
• Compliance events - Stay informed about KYB/KYC updates

How Webhooks Work

1. Event occurs in your Maraboo account (e.g., payment completes)
2. Maraboo sends an HTTP POST request to your webhook URL
3. Your server receives the webhook payload
4. Your server responds with a 2xx status code
5. Your application processes the event data

Available Webhook Events

Transaction Events

• transaction.created - A new transaction has been created
• transaction.updated - A transaction has been updated
• transaction.completed - A transaction has been successfully completed

Wallet Events

• wallet.created - A new wallet has been created
• wallet.updated - A wallet has been updated

Webhook Payload Structure

All webhook payloads follow a consistent structure:

{
  "event_type": "transaction.completed",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "your-correlation-id",
  "reference": "your-reference",
  "data": {
    "metadata": {},
    "environment": "production",
    "transaction_status": "completed",
    "transaction_initiated_at": "2025-10-11T23:29:45.000Z",
    "webhook_initiated_at": "2025-10-11T23:30:00.000Z",
    "transaction_type": "payment",
    "transaction_kind": "payout",
    "failure_reason": null,
    "transaction_amount": 10000,
    "transaction_currency": "USD"
  }
}

Top-level Payload Fields

Field	Type	Description
event_type	string	The type of event that occurred.
webhook_url	string	The URL the webhook was sent to.
correlation_id	string	A unique ID for the webhook event.
reference	string	A reference string for the event.
data	object	An object containing the event data.

data Object Fields

Field	Type	Description
metadata	object	Custom metadata attached to the transaction (client-defined).
environment	string	The environment where the event occurred ("sandbox" or "production").
transaction_status	string	The current status of the transaction.
transaction_initiated_at	string	ISO 8601 timestamp of when the transaction was initiated.
webhook_initiated_at	string	ISO 8601 timestamp of when the webhook was sent.
transaction_type	string	The type of transaction (e.g., "payment").
transaction_kind	string	The kind of transaction (e.g., "payout", "collection").
failure_reason	string | null	The reason for failure if the transaction failed.
transaction_amount	number	The transaction amount in the smallest currency unit.
transaction_currency	string	The three-letter ISO currency code.

Example Payloads

transaction.created

{
  "event_type": "transaction.created",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "cor_12345",
  "reference": "MB-abc123xyz",
  "data": {
    "metadata": {},
    "environment": "production",
    "transaction_status": "pending",
    "transaction_initiated_at": "2025-10-11T23:29:45.000Z",
    "webhook_initiated_at": "2025-10-11T23:29:45.500Z",
    "transaction_type": "payment",
    "transaction_kind": "payout",
    "failure_reason": null,
    "transaction_amount": 10000,
    "transaction_currency": "USD"
  }
}

transaction.updated

{
  "event_type": "transaction.updated",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "cor_67890",
  "reference": "MB-abc123xyz",
  "data": {
    "metadata": {},
    "environment": "production",
    "transaction_status": "processing",
    "transaction_initiated_at": "2025-10-11T23:29:45.000Z",
    "webhook_initiated_at": "2025-10-11T23:29:50.200Z",
    "transaction_type": "payment",
    "transaction_kind": "payout",
    "failure_reason": null,
    "transaction_amount": 10000,
    "transaction_currency": "USD"
  }
}

transaction.completed

{
  "event_type": "transaction.completed",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "cor_abcde",
  "reference": "MB-abc123xyz",
  "data": {
    "metadata": {},
    "environment": "production",
    "transaction_status": "completed",
    "transaction_initiated_at": "2025-10-11T23:29:45.000Z",
    "webhook_initiated_at": "2025-10-11T23:30:00.100Z",
    "transaction_type": "payment",
    "transaction_kind": "payout",
    "failure_reason": null,
    "transaction_amount": 10000,
    "transaction_currency": "USD"
  }
}

wallet.created

{
  "event_type": "wallet.created",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "cor_fghij",
  "reference": "wallet_456",
  "data": {
    "walletId": "wallet_456",
    "walletName": "Main Wallet",
    "currency": "USD",
    "status": "active",
    "balance": 0,
    "createdAt": "2025-10-11T22:15:00.000Z"
  }
}

wallet.updated

{
  "event_type": "wallet.updated",
  "webhook_url": "https://your-webhook-url.com",
  "correlation_id": "cor_klmno",
  "reference": "wallet_456",
  "data": {
    "walletId": "wallet_456",
    "walletName": "Main Wallet - Updated",
    "currency": "USD",
    "status": "active",
    "balance": 10000,
    "previousBalance": 0,
    "updatedAt": "2025-10-11T22:20:00.000Z"
  }
}