Skip to main content
All events are delivered in the standard webhook envelope. The payloads below show the data field contents for each event type.

​
Quick Reference

EventDescription
person.createdA person record was created
person.updatedA person record was updated
user.createdA user account was created
user.updatedA user’s profile was updated
user.profile.updatedA user completed a profile action (e.g., password set)
user.kyc.updatedA user’s KYC status changed
user.kyc.expiryA user’s identity document is expiring or has expired
payroll.createdA payroll was created
payroll.status.updatedA payroll’s status changed
transaction.initiatedA transaction was created for processing
transaction.succeededA transaction completed — payroll disbursement or business account deposit
transaction.failedA transaction failed or was returned
instant-pay.succeededAn instant pay request was completed
contract.createdA contract was created
contract.signedA contract signature was recorded
contract.status.updatedA contract’s status changed
virtual-account.requestedA virtual account was requested
virtual-account.submittedA virtual account request was sent to the bank
virtual-account.createdA virtual account is active with account details
business.kyb.reviewedA KYB submission was reviewed
business.kyb.completedA business completed KYB verification
business.basicinfo.updatedA business’s basic information was updated
external-account.addedAn external bank account was linked
external-account.removedAn external bank account was removed

​
Persons

​
person.created

JSON
{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "personType": "CONTRACTOR",
  "contractorType": "individual",
  "phoneNumber": {
    "countryCode": "1",
    "number": "4155551234"
  },
  "tenantKey": "cad95193904"
}

​
person.updated

JSON
{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phoneNumber": {
    "countryCode": "1",
    "number": "4155551234"
  },
  "tenantKey": "cad95193904"
}

​
Users

​
user.created

JSON
{
  "id": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "personId": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "phoneNumber": {
    "countryCode": "1",
    "number": "4155551234"
  },
  "tenantKey": "cad95193904"
}

​
user.updated

The payload includes a type field indicating what was updated.
TypeDescription
basic_infoName, email, phone number, or tag was updated. isNameUpdated indicates if the name changed.
JSON
{
  "id": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "type": "basic_info",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phoneNumber": {
    "countryCode": "1",
    "number": "4155551234"
  },
  "tag": "",
  "isNameUpdated": false,
  "tenantKey": "cad95193904"
}

​
user.profile.updated

JSON
{
  "id": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "type": "password_set",
  "tenantKey": "cad95193904"
}

​
user.kyc.updated

Fired on every KYC status change. The type field indicates which verification component changed.
JSON
{
  "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "type": "identity",
  "status": "approved",
  "tenantKey": "cad95193904"
}
StatusDescription
processingKYC verification is in progress
approvedVerification successful
rejectedVerification failed — resubmission needed
TypeDescription
identityIdentity document verification
addressAddress verification

​
user.kyc.expiry

Fired when a user’s identity document is approaching expiry or has expired.
JSON
{
  "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "stage": "about-to-expire",
  "documentType": "passport",
  "expiryDate": "2026-03-15",
  "tenantKey": "cad95193904"
}
StageDescription
about-to-expireDocument expires within 30 days
in-grace-periodExpired but within 60-day grace period
expiredPast grace period — user must re-verify

​
Payroll

StatusDescription
savedPayroll is saved
approvedApproved, waiting to be scheduled once funds are collected
scheduledFunds collected, scheduled for payroll date
processingPayroll is being processed
completedPayroll processing complete

​
payroll.created

JSON
{
  "id": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "workerType": "CONTRACTOR",
  "type": "ONE_OFF",
  "tenantKey": "cad95193904"
}

​
payroll.status.updated

JSON
{
  "id": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "status": "approved",
  "tenantKey": "cad95193904"
}

​
Transactions

EventDescription
transaction.initiatedCreated for processing. Preliminary compliance checks complete.
transaction.succeededA transaction completed. Fired for PAYROLL disbursements and DEPOSIT (business virtual account funding).
transaction.failedFailed or returned. Check message for details. If isReturned: true, the transaction was previously successful but returned by the recipient bank.

​
transaction.initiated

JSON
{
  "id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "type": "PAYOUT",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "9bd99534-8c7f-4b2a-b63d-083e33ca205e",
  "tenantKey": "cad95193904"
}

​
transaction.succeeded

Fired when a payroll disbursement completes or when a business virtual account receives funds.
JSON
{
  "id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "type": "PAYROLL",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "9bd99534-8c7f-4b2a-b63d-083e33ca205e",
  "tenantKey": "cad95193904"
}

​
transaction.failed

JSON
{
  "id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "message": "Account inactive",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "type": "PAYOUT",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "9bd99534-8c7f-4b2a-b63d-083e33ca205e",
  "tenantKey": "cad95193904"
}
Returned transactions are delivered as transaction.failed with isReturned: true:
JSON
{
  "id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "message": "Account closed",
  "isReturned": true,
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "type": "PAYOUT",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "9bd99534-8c7f-4b2a-b63d-083e33ca205e",
  "tenantKey": "cad95193904"
}
  • type is PAYROLL for payroll disbursements and DEPOSIT for business virtual account funding.
  • reference is the payrollId for PAYROLL transactions and the deposit reference for DEPOSIT transactions.
  • recipientId is the userId for Cadana wallet payments and the beneficiaryId for direct bank payments. For DEPOSIT, it is the receiving account ID.

​
Instant Pay

​
instant-pay.succeeded

JSON
{
  "id": "c5d6e7f8-a901-2345-cdef-567890123456",
  "personId": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "tenantKey": "cad95193904"
}

​
Contracts

​
contract.created

JSON
{
  "id": "d6e7f8a9-0123-4567-def0-678901234567",
  "personId": "ee278b2d-cbd8-4104-8af4-f02a41566894",
  "templateId": "4f8220e5-f6b5-43cb-963e-e99219ed1736",
  "tenantKey": "cad95193904"
}

​
contract.signed

JSON
{
  "id": "d6e7f8a9-0123-4567-def0-678901234567",
  "signatureId": "2dee5427-c648-4696-89cc-95e4d942cd24",
  "name": "John Doe",
  "email": "john@example.com",
  "isComplete": false,
  "tenantKey": "cad95193904"
}

​
contract.status.updated

JSON
{
  "id": "d6e7f8a9-0123-4567-def0-678901234567",
  "status": "revoked",
  "tenantKey": "cad95193904"
}

​
Virtual Accounts

A virtual account can belong to either a user or a business. Exactly one of userId or businessId will be present.

​
virtual-account.requested

JSON
{
  "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
  "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "currency": "USD",
  "status": "requested",
  "description": "in review",
  "tenantKey": "cad95193904"
}

​
virtual-account.submitted

JSON
{
  "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
  "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "currency": "USD",
  "status": "submitted",
  "description": "sent to bank for processing",
  "tenantKey": "cad95193904"
}

​
virtual-account.created

JSON
{
  "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
  "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
  "currency": "USD",
  "status": "active",
  "accountInformation": {
    "accountNumber": "000000000000",
    "accountName": "JOHN DOE",
    "bankName": "Example Bank",
    "bankCode": "000000000",
    "countryCode": "US",
    "accountType": "Checking",
    "routingNumber": "000000000",
    "bankAddress": "1800 Main St., San Francisco, CA 94105"
  },
  "tenantKey": "cad95193904"
}

​
Business

​
business.kyb.reviewed

Sent when a KYB submission has been reviewed. May indicate approval or that additional information is needed.
JSON
{
  "tenantKey": "cad95193904",
  "status": "needsAdditionalInformation",
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "businessName": "Acme Corporation",
  "requirements": {
    "currentlyDue": [
      "principals.0.firstName",
      "principals.0.documentsRequired.identityFileId",
      "entityName"
    ],
    "errors": [
      {
        "field": "entityName",
        "reason": "Only english letters are allowed"
      },
      {
        "field": "principals.0.firstName",
        "reason": "Name doesn't match ID document"
      }
    ]
  }
}
See KYB Requirements for handling needsAdditionalInformation responses.

​
business.kyb.completed

JSON
{
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "businessName": "Acme Corporation",
  "status": "completed",
  "tenantKey": "cad95193904"
}

​
business.basicinfo.updated

JSON
{
  "id": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "name": "Acme Corporation",
  "registrationId": "REG123456",
  "tenantKey": "cad95193904"
}

​
External Accounts

​
external-account.added

JSON
{
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "tenantKey": "cad95193904",
  "accounts": [
    {
      "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
      "accountNumber": "0000",
      "bankName": "First National Bank - Checking",
      "status": "active"
    }
  ]
}

​
external-account.removed

JSON
{
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "tenantKey": "cad95193904",
  "accounts": [
    {
      "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
      "accountNumber": "0000",
      "bankName": "First National Bank - Checking",
      "status": "removed"
    }
  ]
}