Events - Cadana Developers

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

Quick Reference

Event	Description
`person.created`	A person record was created
`person.updated`	A person record was updated
`person.offboarding.scheduled`	Offboarding was scheduled for a person
`person.offboarding.cancelled`	A pending offboarding was cancelled
`person.offboarding.completed`	A person transitioned to Former status
`person.reinstated`	A former person was reinstated to Active status
`user.created`	A user account was created
`user.updated`	A user’s profile was updated
`user.profile.updated`	A user completed a profile action (e.g., password set)
`user.kyc.updated`	A user’s KYC status changed
`user.kyc.expiry`	A user’s identity document is expiring or has expired
`payroll.created`	A payroll was created
`payroll.status.updated`	A payroll’s status changed
`transaction.initiated`	A transaction was created for processing
`transaction.succeeded`	A transaction completed — payroll disbursement or business account deposit
`transaction.failed`	A transaction failed or was returned
`instant-pay.succeeded`	An instant pay request was completed
`contract.created`	A contract was created
`contract.signed`	A contract signature was recorded
`contract.status.updated`	A contract’s status changed
`virtual-account.requested`	A virtual account was requested
`virtual-account.submitted`	A virtual account request was sent to the bank
`virtual-account.created`	A virtual account is active with account details
`business.kyb.reviewed`	A KYB submission was reviewed
`business.kyb.rejected`	A KYB submission was rejected (terminal)
`business.kyb.completed`	A business completed KYB verification
`business.basicinfo.updated`	A business’s basic information was updated
`external-account.added`	An external bank account was linked
`external-account.removed`	An external bank account was removed
`filing.created`	A statutory filing was created
`filing.blocked`	A filing is blocked by missing requirements
`filing.pending`	A blocked filing was unblocked and is pending again
`filing.in_review`	A filing is validated and ready for approval
`filing.approved`	A filing was approved for submission
`filing.submitted`	A filing was submitted to the government authority
`filing.accepted`	The government authority accepted the filing
`filing.rejected`	The government authority rejected the filing
`filing.overdue`	A filing is past its due date
`remittance.created`	A government payment was initiated
`remittance.processing`	A government payment is being processed
`remittance.completed`	A government payment was completed
`remittance.failed`	A government payment failed
`requirement.created`	A compliance requirement was surfaced
`requirement.satisfied`	A compliance requirement was resolved

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"
}

Offboarding

Offboarding events track a person’s lifecycle from active employment through exit and potential reinstatement. See Offboard Workers for the full guide.

person.offboarding.scheduled

JSON

{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "exitDate": "2025-06-30",
  "reason": "Voluntary resignation",
  "tenantKey": "cad95193904"
}

person.offboarding.cancelled

JSON

{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "tenantKey": "cad95193904"
}

person.offboarding.completed

JSON

{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "exitDate": "2025-06-30",
  "reason": "Voluntary resignation",
  "tenantKey": "cad95193904"
}

person.reinstated

JSON

{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "tenantKey": "cad95193904"
}

To get full offboarding details (compensation, payroll inclusion), query GET /v1/persons/{personId} after receiving the event.

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.

Type	Description
`basic_info`	Name, 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"
}

Status	Description
`processing`	KYC verification is in progress
`approved`	Verification successful
`rejected`	Verification failed — resubmission needed

Type	Description
`identity`	Identity document verification
`address`	Address 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"
}

Stage	Description
`about-to-expire`	Document expires within 30 days
`in-grace-period`	Expired but within 60-day grace period
`expired`	Past grace period — user must re-verify

Payroll

Status	Description
`saved`	Payroll is saved
`approved`	Approved, waiting to be scheduled once funds are collected
`scheduled`	Funds collected, scheduled for payroll date
`processing`	Payroll is being processed
`completed`	Payroll 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

Event	Description
`transaction.initiated`	Created for processing. Preliminary compliance checks complete.
`transaction.succeeded`	A transaction completed. Fired for `PAYROLL` disbursements and `DEPOSIT` (business virtual account funding).
`transaction.failed`	Failed 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.

PAYROLL
DEPOSIT

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"
}

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": {
    "currency": "USD",
    "amount": 500000
  },
  "type": "DEPOSIT",
  "reference": "dep-ref-001",
  "recipientId": "acct-9bd99534-8c7f-4b2a",
  "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.rejected

Sent when a KYB submission has been permanently rejected. This is a terminal state — the business cannot resubmit.

JSON

{
  "id": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "businessName": "Acme Corporation",
  "reason": "Business does not meet compliance requirements",
  "status": "rejected",
  "tenantKey": "cad95193904",
  "timestamp": 1765359752
}

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"
    }
  ]
}

Statutory Compliance

Filing, remittance, and requirement events share a common structure. The resourceType and resourceId fields identify the affected resource.

filing.created

JSON

{
  "resourceType": "filing",
  "resourceId": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01ABC",
  "actor": { "type": "system", "id": null },
  "data": {
    "filingType": "ISR Withholding",
    "countryCode": "MX",
    "periodLabel": "February 2026",
    "status": "pending",
    "workerCount": 15
  }
}

filing.blocked

JSON

{
  "resourceType": "filing",
  "resourceId": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01ABC",
  "actor": { "type": "system", "id": null },
  "data": {
    "filingType": "ISR Withholding",
    "countryCode": "MX",
    "periodLabel": "February 2026",
    "status": "blocked",
    "blockedReasons": [
      {
        "code": "missing_worker_data",
        "message": "3 workers are missing Tax Identification Numbers"
      }
    ]
  }
}

filing.approved

JSON

{
  "resourceType": "filing",
  "resourceId": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01ABC",
  "actor": { "type": "user", "id": "usr_01PQR" },
  "data": {
    "filingType": "ISR Withholding",
    "countryCode": "MX",
    "periodLabel": "February 2026",
    "status": "approved"
  }
}

filing.accepted

JSON

{
  "resourceType": "filing",
  "resourceId": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01ABC",
  "actor": { "type": "authority", "id": null },
  "data": {
    "filingType": "ISR Withholding",
    "countryCode": "MX",
    "periodLabel": "February 2026",
    "status": "accepted",
    "filedAt": "2026-03-04T09:15:00Z"
  }
}

remittance.completed

JSON

{
  "resourceType": "remittance",
  "resourceId": "rem_01STU",
  "businessId": "biz_01ABC",
  "actor": { "type": "system", "id": null },
  "data": {
    "countryCode": "MX",
    "authority": "SAT",
    "status": "completed",
    "amount": 125000.00,
    "currency": "MXN",
    "paymentReference": "SAT-2026-02-RFC-XAXX010101000-ISR"
  }
}

requirement.satisfied

JSON

{
  "resourceType": "requirement",
  "resourceId": "req_01XYZ",
  "businessId": "biz_01ABC",
  "actor": { "type": "system", "id": null },
  "data": {
    "name": "SAT Employer RFC",
    "category": "business_tax_parameter",
    "countryCode": "MX",
    "status": "satisfied",
    "unblockedFilings": ["fil_01HQ3K4N7XYZABC"]
  }
}

Overview

Payments API

Wallets API

Workforce API

Tax API

Statutory Compliance API

​Quick Reference

​Persons

​person.created

​person.updated

​Offboarding

​person.offboarding.scheduled

​person.offboarding.cancelled

​person.offboarding.completed

​person.reinstated

​Users

​user.created

​user.updated

​user.profile.updated

​user.kyc.updated

​user.kyc.expiry

​Payroll

​payroll.created

​payroll.status.updated

​Transactions

​transaction.initiated

​transaction.succeeded

​transaction.failed

​Instant Pay

​instant-pay.succeeded

​Contracts

​contract.created

​contract.signed

​contract.status.updated

​Virtual Accounts

​virtual-account.requested

​virtual-account.submitted

​virtual-account.created

​Business

​business.kyb.reviewed

​business.kyb.rejected

​business.kyb.completed

​business.basicinfo.updated

​External Accounts

​external-account.added

​external-account.removed

​Statutory Compliance

​filing.created

​filing.blocked

​filing.approved

​filing.accepted

​remittance.completed

​requirement.satisfied

Quick Reference

Persons

person.created

person.updated

Offboarding

person.offboarding.scheduled

person.offboarding.cancelled

person.offboarding.completed

person.reinstated

Users

user.created

user.updated

user.profile.updated

user.kyc.updated

user.kyc.expiry

Payroll

payroll.created

payroll.status.updated

Transactions

transaction.initiated

transaction.succeeded

transaction.failed

Instant Pay

instant-pay.succeeded

Contracts

contract.created

contract.signed

contract.status.updated

Virtual Accounts

virtual-account.requested

virtual-account.submitted

virtual-account.created

Business

business.kyb.reviewed

business.kyb.rejected

business.kyb.completed

business.basicinfo.updated

External Accounts

external-account.added

external-account.removed

Statutory Compliance

filing.created

filing.blocked

filing.approved

filing.accepted

remittance.completed

requirement.satisfied