Skip to main content
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

FieldTypeDescription
eventstringEvent type identifier
data.idstringUnique transaction identifier
data.amountfloatTransaction amount in specified currency
data.currencystringCurrency code (NGN)
data.transactionTypestringType of transaction (CREDIT for incoming)
data.entryDatedatetimeISO 8601 timestamp of transaction
data.uniqueRefstringUnique reference for the transaction
data.accountobjectAccount details where transaction occurred
data.beneficiaryobjectRecipient account information (your Carbon account)
data.beneficiary.accountNamestringName of the receiving account holder
data.beneficiary.accountNumberstringReceiving account number
data.beneficiary.bankNamestringName of the receiving bank
data.senderobjectSender account information (external sender)
data.sender.accountNamestringName of the sender account holder
data.sender.accountNumberstringSender’s account number
data.sender.bankNamestringName of the sender’s bank
data.transactionDetailsobjectAdditional transaction information
data.transactionDetails.remarkstringTransaction 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

FieldTypeDescription
eventstringEvent type identifier
data.idstringUnique transaction identifier
data.amountfloatTransaction amount in specified currency
data.currencystringCurrency code (NGN)
data.transactionTypestringType of transaction (DEBIT for outgoing)
data.entryDatedatetimeISO 8601 timestamp of transaction
data.uniqueRefstringReference used in the original payout request
data.accountobjectSource account details for the transaction
data.beneficiaryobjectRecipient account information
data.beneficiary.accountNamestringName of the beneficiary account holder
data.beneficiary.accountNumberstringBeneficiary’s account number
data.beneficiary.bankNamestringName of the beneficiary’s bank
data.senderobjectSender account information
data.sender.accountNamestringName of the sender account holder
data.sender.accountNumberstringSender’s account number
data.sender.bankNamestringName of the sender’s bank
data.transactionDetailsobjectAdditional transaction information
data.transactionDetails.remarkstringTransaction description or note

​
Implementation Notes

Always respond with a 2xx status code to acknowledge receipt. Carbon will retry delivery if no acknowledgment is received.
Use the data.id field to handle duplicate events gracefully. The same transaction may trigger multiple webhook deliveries.
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.