Webhook Events - Carbon Business API

Carbon provides webhook events to notify your application about specific account activities in real-time. Below are the details of the supported webhook events and their payload structures.

Available Events

`account.incoming-transaction`

This event is triggered when an incoming transaction is received in your account, such as when a customer makes a payment to your collection account.

Use this event to automatically process incoming payments, update account balances, or trigger downstream business logic.

Payload Structure

{
    "event": "account.incoming-transaction",
    "data": {
        "id": "b44b9f33-179d-5d0g-0bbd-d4340387fcb2",
        "amount": 150000.00,
        "currency": "NGN",
        "transactionType": "CREDIT",
        "entryDate": "2026-01-19T10:30:45.048+0000",
        "uniqueRef": "209701944078087",
        "account": {
            "id": "5999182f-bccd-548f-bcee-c4350397fdc2",
            "bankAccount": {
                "accountName": "CARBON BUSINESS DEMO - JOHN DOE",
                "accountNumber": "0340899288",
                "bank": {
                    "code": "565",
                    "name": "CARBON"
                }
            },
            "static": true,
            "currency": "NGN",
            "clientId": "528530847"
        },
        "beneficiary": {
            "accountName": "CARBON BUSINESS DEMO - JOHN DOE",
            "accountNumber": "0340899288",
            "bankName": "CARBON"
        },
        "sender": {
            "accountName": "JANE SMITH",
            "accountNumber": "2001234567",
            "bankName": "GTBank"
        },
        "transactionDetails": {
            "remark": "TRF/TO/0340899288/Payment for services"
        }
    }
}

Key Fields

Field	Type	Description
`event`	string	Event type identifier
`data.id`	string	Unique transaction identifier
`data.amount`	float	Transaction amount in specified currency
`data.currency`	string	Currency code (NGN)
`data.transactionType`	string	Type of transaction (CREDIT for incoming)
`data.entryDate`	datetime	ISO 8601 timestamp of transaction
`data.uniqueRef`	string	Unique reference for the transaction
`data.account`	object	Account details where transaction occurred
`data.beneficiary`	object	Recipient account information (your Carbon account)
`data.beneficiary.accountName`	string	Name of the receiving account holder
`data.beneficiary.accountNumber`	string	Receiving account number
`data.beneficiary.bankName`	string	Name of the receiving bank
`data.sender`	object	Sender account information (external sender)
`data.sender.accountName`	string	Name of the sender account holder
`data.sender.accountNumber`	string	Sender’s account number
`data.sender.bankName`	string	Name of the sender’s bank
`data.transactionDetails`	object	Additional transaction information
`data.transactionDetails.remark`	string	Transaction description or note

`account.outgoing-transaction`

This event is triggered when an outgoing transaction is made from your account, such as when you process a payout to a beneficiary.

Use this event to track payout completions, update transaction records, or notify users about successful transfers.

Payload Structure

{
    "event": "account.outgoing-transaction",
    "data": {
        "id": "a33a8f22-068c-4c9f-9aac-c98edaf7a698",
        "amount": 10157.5,
        "currency": "NGN",
        "transactionType": "DEBIT",
        "entryDate": "2026-01-19T12:44:44.048+0000",
        "uniqueRef": "208690833967976",
        "account": {
            "id": "4888071e-abbe-437e-abdf-b3239286ebc1",
            "bankAccount": {
                "accountName": "CARBON BUSINESS DEMO - MARK ERELU",
                "accountNumber": "0340899287",
                "bank": {
                    "code": "565",
                    "name": "CARBON"
                }
            },
            "static": true,
            "currency": "NGN",
            "clientId": "528530846"
        },
        "beneficiary": {
            "accountName": "DOE JOHN",
            "accountNumber": "9002118329",
            "bankName": "Paycom (Opay)"
        },
        "sender": {
            "accountName": "CARBON BUSINESS DEMO - MARK ERELU",
            "accountNumber": "0340899287",
            "bankName": "CARBON"
        },
        "transactionDetails": {
            "remark": "TRF/FRM/9002118329/TEST - 100"
        }
    }
}

Key Fields

Field	Type	Description
`event`	string	Event type identifier
`data.id`	string	Unique transaction identifier
`data.amount`	float	Transaction amount in specified currency
`data.currency`	string	Currency code (NGN)
`data.transactionType`	string	Type of transaction (DEBIT for outgoing)
`data.entryDate`	datetime	ISO 8601 timestamp of transaction
`data.uniqueRef`	string	Reference used in the original payout request
`data.account`	object	Source account details for the transaction
`data.beneficiary`	object	Recipient account information
`data.beneficiary.accountName`	string	Name of the beneficiary account holder
`data.beneficiary.accountNumber`	string	Beneficiary’s account number
`data.beneficiary.bankName`	string	Name of the beneficiary’s bank
`data.sender`	object	Sender account information
`data.sender.accountName`	string	Name of the sender account holder
`data.sender.accountNumber`	string	Sender’s account number
`data.sender.bankName`	string	Name of the sender’s bank
`data.transactionDetails`	object	Additional transaction information
`data.transactionDetails.remark`	string	Transaction description or note

Loan Events

Carbon fires the following events throughout the loan lifecycle. Subscribe to these to track application progress and drive your customer-facing UI.

`loan.application.received`

Fired when a loan application is successfully submitted.

Payload Structure

{
  "event": "loan.application.received",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "amount": 2000000,
    "repayment_period": 3,
    "status": "PENDING",
    "created_at": "2024-05-15T10:00:00Z"
  }
}

`loan.kyc.pending`

Fired when KYC verification is initiated for a loan application.

Payload Structure

{
  "event": "loan.kyc.pending",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "kyc_status": "PENDING"
  }
}

`loan.offer.generated`

Fired when underwriting completes and an offer is ready for the customer.

Payload Structure

{
  "event": "loan.offer.generated",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "offered_amount": 2000000,
    "tenure": 3,
    "interest_rate": 8,
    "monthly_repayment": 719999,
    "expires_at": "2024-06-15T10:00:00Z"
  }
}

`loan.offer.accepted`

Fired when the customer accepts the loan offer.

Payload Structure

{
  "event": "loan.offer.accepted",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "status": "ACCEPTED_OFFER"
  }
}

`loan.offer.declined`

Fired when the customer declines the loan offer.

Payload Structure

{
  "event": "loan.offer.declined",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "decline_reason": "HIGH_INTEREST"
  }
}

`loan.offer.expired`

Fired when a loan offer expires without the customer taking action.

Payload Structure

{
  "event": "loan.offer.expired",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "expired_at": "2024-06-15T10:00:00Z"
  }
}

`loan.application.declined`

Fired when the application is rejected by the credit decisioning engine.

Payload Structure

{
  "event": "loan.application.declined",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "decline_reasons": ["INSUFFICIENT_REVENUE", "HIGH_EXISTING_DEBT"]
  }
}

`loan.application.approved`

Fired when the loan is approved for disbursement by a Carbon admin.

Payload Structure

{
  "event": "loan.application.approved",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "approved_amount": 2000000
  }
}

`loan.disbursed`

Fired when loan funds are disbursed to the customer’s account. The loan_id field becomes available after this event — use it for repayment routes.

Payload Structure

{
  "event": "loan.disbursed",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "disbursed_amount": 2000000,
    "disbursement_date": "2024-05-20T08:00:00Z"
  }
}

`loan.arrears`

Fired when a loan becomes overdue.

Payload Structure

{
  "event": "loan.arrears",
  "data": {
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "outstanding_balance": 150000000,
    "days_overdue": 7
  }
}

`loan.closed`

Fired when the loan is fully repaid.

Payload Structure

{
  "event": "loan.closed",
  "data": {
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "closed_at": "2024-08-20T12:00:00Z"
  }
}

`loan.repayment.successful`

Fired when a repayment charge succeeds.

Payload Structure

{
  "event": "loan.repayment.successful",
  "data": {
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "amount": 7199999,
    "reference": "REPAY_REF_20250215_001",
    "outstanding_balance": 142800001,
    "repayment_date": "2025-02-15T09:00:00Z"
  }
}

`loan.repayment.failed`

Fired when a repayment charge attempt fails.

Payload Structure

{
  "event": "loan.repayment.failed",
  "data": {
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "amount": 7199999,
    "reference": "REPAY_REF_20250215_001",
    "failure_reason": "INSUFFICIENT_FUNDS"
  }
}

`loan.repayment.due`

Fired 3 days before a repayment due date as a reminder.

Payload Structure

{
  "event": "loan.repayment.due",
  "data": {
    "loan_id": "LOAN_ABC123",
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "amount_due": 7199999,
    "due_date": "2025-02-15"
  }
}

Implementation Notes

Event Processing

Always respond with a 2xx status code to acknowledge receipt. Carbon will retry delivery if no acknowledgment is received.

Idempotency

Use the data.id field to handle duplicate events gracefully. The same transaction may trigger multiple webhook deliveries.

Signature Verification

Always verify webhook signatures before processing events to ensure they originate from Carbon.

Next Steps

For more information on setting up and managing webhooks, refer to the Webhooks Introduction documentation.

​Available Events

​account.incoming-transaction

​Payload Structure

​Key Fields

​account.outgoing-transaction

​Payload Structure

​Key Fields

​Loan Events

​loan.application.received

​Payload Structure

​loan.kyc.pending

​Payload Structure

​loan.offer.generated

​Payload Structure

​loan.offer.accepted

​Payload Structure

​loan.offer.declined

​Payload Structure

​loan.offer.expired

​Payload Structure

​loan.application.declined

​Payload Structure

​loan.application.approved

​Payload Structure

​loan.disbursed

​Payload Structure

​loan.arrears

​Payload Structure

​loan.closed

​Payload Structure

​loan.repayment.successful

​Payload Structure

​loan.repayment.failed

​Payload Structure

​loan.repayment.due

​Payload Structure

​Implementation Notes

​Next Steps

Available Events

`account.incoming-transaction`

Payload Structure

Key Fields

`account.outgoing-transaction`

Payload Structure

Key Fields

Loan Events

`loan.application.received`

Payload Structure

`loan.kyc.pending`

Payload Structure

`loan.offer.generated`

Payload Structure

`loan.offer.accepted`

Payload Structure

`loan.offer.declined`

Payload Structure

`loan.offer.expired`

Payload Structure

`loan.application.declined`

Payload Structure

`loan.application.approved`

Payload Structure

`loan.disbursed`

Payload Structure

`loan.arrears`

Payload Structure

`loan.closed`

Payload Structure

`loan.repayment.successful`

Payload Structure

`loan.repayment.failed`

Payload Structure

`loan.repayment.due`

Payload Structure

Implementation Notes

Next Steps