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.processing`	A transaction passed compliance checks and is being processed
`transaction.rfi.updated`	Additional information was requested or provided for a transaction under review
`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
`invoice.contractor.submitted`	A contractor submitted an invoice for review
`invoice.contractor.approved`	A contractor invoice was approved
`invoice.contractor.rejected`	A contractor invoice was rejected
`invoice.contractor.paid`	A payment was recorded against a contractor invoice
`reimbursement.submitted`	A reimbursement was submitted for review
`reimbursement.approved`	A reimbursement was approved
`reimbursement.rejected`	A reimbursement was rejected
`reimbursement.paid`	A reimbursement was paid out
`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
`pending`	The provider returned an inconclusive result and a manual review is underway
`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. The webhook uses its own status vocabulary — the third column shows the corresponding status on GET /v1/payrolls/{id}. See Payroll Lifecycle for the full lifecycle.

`status` value	Description	Status on GET
`saved`	Entries added, ready for approval	`Pending Submission`
`approved`	Payroll approved, funds not yet collected	`Awaiting Funds`
`scheduled`	Funds collected, queued for the payroll date	`Scheduled`
`processing`	Disbursements being sent to workers	`Processing`
`completed`	All disbursements confirmed	`Completed`

Awaiting Funds is the status a payroll holds between the approved and scheduled events — receiving approved with no scheduled following shortly means the payroll is waiting on funds; it proceeds automatically once the business balance covers it. No webhook fires for Rejected or Deleted; poll GET /v1/payrolls/{id} to detect those.

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.processing`	The transaction passed compliance checks and is being processed.
`transaction.rfi.updated`	Additional information was requested (`status: RFI_REQUESTED`) or provided (`status: RFI_PROVIDED`) for a transaction under review.
`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.processing

Fires once per transaction, when it passes compliance checks and is being processed. Most transactions pass checks automatically within seconds of transaction.initiated; transactions held for manual review can stay in the initiated state for longer before this event fires.

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

Instantly-settling transactions (for example PAYROLL_FEE wallet debits) can move straight from transaction.initiated to transaction.succeeded without a transaction.processing event, so treat this event as optional in the lifecycle. It is delivered at most once per transaction.

transaction.rfi.updated

Fires when additional information is needed for a transaction under review, and again when that information has been provided. While a request for information is open, the transaction stays in the initiated state; once review completes, the transaction continues its normal lifecycle (transaction.processing on approval, transaction.failed otherwise). status is RFI_REQUESTED when information is being requested — actionRequired describes what is needed — and RFI_PROVIDED once it has been submitted (the actionRequired field is omitted).

JSON

{
  "id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "type": "PAYOUT",
  "status": "RFI_REQUESTED",
  "actionRequired": "Please provide an invoice for this payment",
  "reference": "9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "recipientId": "9bd99534-8c7f-4b2a-b63d-083e33ca205e",
  "recipientType": "BUSINESS",
  "tenantKey": "cad95193904"
}

Use this event to surface “action needed” states in your UI — a transaction with an open request for information will otherwise look like a long-running initiated transaction.

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

Invoices

These events cover the contractor self-submitted invoice lifecycle: a contractor raises an invoice billed to your business, you review it, and it is paid. invoice.contractor.submitted is your cue to review — call POST /v1/invoices/{invoiceId}/review to approve or reject it. Only invoices with source of CONTRACTOR_SUBMITTED fire these events. reason is present only on invoice.contractor.rejected.

invoice.contractor.submitted
invoice.contractor.approved
invoice.contractor.rejected
invoice.contractor.paid

JSON

{
  "id": "f8a9b0c1-2345-6789-bcde-f01234567890",
  "invoiceNumber": "1764332528",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "C123456234",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "datePayable": "2025-12-15",
  "date": "2025-11-28",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "f8a9b0c1-2345-6789-bcde-f01234567890",
  "invoiceNumber": "1764332528",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "C123456234",
  "handledBy": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "f8a9b0c1-2345-6789-bcde-f01234567890",
  "invoiceNumber": "1764332528",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "C123456234",
  "handledBy": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "reason": "Amount does not match the agreed scope",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "f8a9b0c1-2345-6789-bcde-f01234567890",
  "invoiceNumber": "1764332528",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "C123456234",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "paymentDate": "2025-12-10",
  "reference": "PAYROLL-9af0f05e-1efa-407b-be23-8595f89a1b2a",
  "tenantKey": "cad95193904"
}

Reimbursements

These events cover the reimbursement lifecycle: a worker submits a reimbursement — or you create one via POST /v1/reimbursements — you review it, and it is paid out. reimbursement.submitted is your cue to review — call POST /v1/reimbursements/{reimbursementId}/review to approve or reject it. Approving disburses the reimbursement from the sourceCurrency wallet, and reimbursement.paid follows once it settles. reason is present only on reimbursement.rejected; amount is the reimbursed (destination) amount.

reimbursement.submitted
reimbursement.approved
reimbursement.rejected
reimbursement.paid

JSON

{
  "id": "d1e2f3a4-5678-9012-cdef-345678901234",
  "title": "Client dinner",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "9b8a7c6d-5e4f-3210-9876-543210fedcba",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "d1e2f3a4-5678-9012-cdef-345678901234",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "9b8a7c6d-5e4f-3210-9876-543210fedcba",
  "handledBy": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "d1e2f3a4-5678-9012-cdef-345678901234",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "9b8a7c6d-5e4f-3210-9876-543210fedcba",
  "handledBy": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
  "reason": "Receipts missing",
  "tenantKey": "cad95193904"
}

JSON

{
  "id": "d1e2f3a4-5678-9012-cdef-345678901234",
  "personId": "c5d6e7f8-9012-3456-cdef-789012345678",
  "userId": "a3b4c5d6-e7f8-9012-abcd-ef3456789012",
  "businessId": "9b8a7c6d-5e4f-3210-9876-543210fedcba",
  "amount": {
    "currency": "USD",
    "amount": 100000
  },
  "disbursementId": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
  "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

{
  "id": "7c74cc95-d7c6-4537-b388-6d57ed020b34",
  "tenantKey": "cad95193904",
  "status": "needs-additional-info",
  "timestamp": 1765359752,
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "businessName": "Acme Corporation",
  "requirements": {
    "currentlyDue": [
      "principals.0.firstName",
      "principals.0.identifier.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 needs-additional-info 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

{
  "id": "7c74cc95-d7c6-4537-b388-6d57ed020b34",
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "businessName": "Acme Corporation",
  "status": "complete",
  "timestamp": 1765359752,
  "tenantKey": "cad95193904"
}

business.basicinfo.updated

JSON

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

External Accounts

external-account.added

Instantly verified
Awaiting micro-deposit

Ready to use for deposits straight away.

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

Submitted, but not usable until the account holder verifies a test deposit.

{
  "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
  "tenantKey": "cad95193904",
  "accounts": [
    {
      "id": "ca51f42c-0adc-4a77-8dd1-a03dd4fb955f",
      "accountNumber": "0000",
      "bankName": "First National Bank - Checking",
      "status": "needs_confirmation",
      "microdepositInfo": {
        "type": "descriptor_code",
        "verificationUrl": "https://verify.example.com/microdeposit/1A2B3C",
        "arrivalDate": 1715583600
      }
    }
  ]
}

status is active for instantly verified accounts, or needs_confirmation for accounts still awaiting micro-deposit verification. This event fires as soon as the account is submitted, so it is the signal to move a customer off your “set up direct debit” prompt. microdepositInfo is present only while an account is awaiting verification. type is descriptor_code (a code on the statement) or amounts (two small deposits to read back), and arrivalDate is a Unix timestamp for when the deposit is expected — enough to render your interim copy without a follow-up API call. To collect the code or amounts, send the account holder to the link from Generate External Account Link with mode set to verification. Poll Get External Accounts if you need to reliably detect the needs_confirmation → active transition: the follow-up event carries a different id for the same account, so the two cannot be correlated by id alone.

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

​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.processing

​transaction.rfi.updated

​transaction.succeeded

​transaction.failed

​Instant Pay

​instant-pay.succeeded

​Contracts

​contract.created

​contract.signed

​contract.status.updated

​Invoices

​Reimbursements

​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.processing

transaction.rfi.updated

transaction.succeeded

transaction.failed

Instant Pay

instant-pay.succeeded

Contracts

contract.created

contract.signed

contract.status.updated

Invoices

Reimbursements

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