> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Comprehensive guide to Carbon Business API webhook events and their payload structures.

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.

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

#### Payload Structure

```json theme={null}
{
    "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.

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

#### Payload Structure

```json theme={null}
{
    "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Event Processing">
    Always respond with a 2xx status code to acknowledge receipt. Carbon will retry delivery if no acknowledgment is received.
  </Accordion>

  <Accordion title="Idempotency">
    Use the `data.id` field to handle duplicate events gracefully. The same transaction may trigger multiple webhook deliveries.
  </Accordion>

  <Accordion title="Signature Verification">
    <Warning>
      Always verify webhook signatures before processing events to ensure they originate from Carbon.
    </Warning>
  </Accordion>
</AccordionGroup>

## Next Steps

For more information on setting up and managing webhooks, refer to the [Webhooks Introduction](/webhooks/introduction) documentation.