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 successfully
`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

The payroll.status.updated event fires for the values below. See Payroll Lifecycle for the full lifecycle.

`status` value	Description
`saved`	Entries added, ready for approval
`approved`	Payroll approved
`scheduled`	Funds collected, queued for the payroll date
`processing`	Disbursements being sent to workers
`completed`	All disbursements confirmed

No webhook fires when a payroll enters Awaiting Funds, Rejected, or Deleted. Poll GET /v1/payrolls/{id} if you need to detect those states.

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

Every transaction.* event carries a type field identifying the kind of transaction:

`type`	Description
`PAYROLL`	A worker payment from a payroll run.
`DEPOSIT`	Funds received into a business virtual account.
`PAYOUT`	A direct user-initiated payout or a business payout.
`PAYROLL_FEE`	A processing fee charged when a payroll runs, debited from the business wallet.

And a recipientType field identifying what kind of entity recipientId refers to:

`recipientType`	When you’ll see it
`BUSINESS`	Business payouts, business-account deposits, and payroll fee charges.
`USER`	Worker wallet payments and direct user payouts.
`EMPLOYEE`	Worker direct bank payments where the worker is classified as an employee.
`CONTRACTOR`	Worker direct bank payments where the worker is classified as a contractor.

Event	Description
`transaction.initiated`	A transaction was created for processing.
`transaction.succeeded`	A transaction succeeded.
`transaction.failed`	A transaction failed or was 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",
  "recipientType": "BUSINESS",
  "tenantKey": "cad95193904"
}

transaction.succeeded

PAYROLL
DEPOSIT
PAYROLL_FEE

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",
  "recipientType": "USER",
  "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",
  "recipientType": "BUSINESS",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "c7d8e9f0-1234-5678-90ab-cdef12345678",
  "amount": {
    "currency": "USD",
    "amount": 2500
  },
  "type": "PAYROLL_FEE",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "recipientType": "BUSINESS",
  "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",
  "recipientType": "BUSINESS",
  "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",
  "recipientType": "BUSINESS",
  "tenantKey": "cad95193904"
}

The type field tells you the kind of transaction. reference is a stable identifier from the source system: payrollId for PAYROLL, the deposit reference for DEPOSIT, the business payout reference for PAYOUT. recipientId is the ID of whoever is receiving funds — use recipientType to interpret it (a userId when recipientType: "USER", a businessId when BUSINESS, a personId when EMPLOYEE or CONTRACTOR).

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

Documentation Index

​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