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


Persons

person.created

JSON

person.updated

JSON

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

person.offboarding.cancelled

JSON

person.offboarding.completed

JSON

person.reinstated

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

Users

user.created

JSON

user.updated

The payload includes a type field indicating what was updated.
JSON

user.profile.updated

JSON

user.kyc.updated

Fired on every KYC status change. The type field indicates which verification component changed.
JSON

user.kyc.expiry

Fired when a user’s identity document is approaching expiry or has expired.
JSON

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

payroll.status.updated

JSON

Transactions

Every transaction.* event carries a type field identifying the kind of transaction: And a recipientType field identifying what kind of entity recipientId refers to:

transaction.initiated

JSON

transaction.succeeded

JSON

transaction.failed

JSON
Returned transactions are delivered as transaction.failed with isReturned: true:
JSON
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

Contracts

contract.created

JSON

contract.signed

JSON

contract.status.updated

JSON

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.
JSON

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.
JSON

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

virtual-account.submitted

JSON

virtual-account.created

JSON

Business

business.kyb.reviewed

Sent when a KYB submission has been reviewed. May indicate approval or that additional information is needed.
JSON
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

business.kyb.completed

JSON

business.basicinfo.updated

JSON

External Accounts

external-account.added

JSON
status is active for instantly verified accounts, or needs_confirmation for accounts still awaiting micro-deposit verification. Poll Get External Accounts if you need to reliably detect the needs_confirmationactive transition.

external-account.removed

JSON

Statutory Compliance

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

filing.created

JSON

filing.blocked

JSON

filing.approved

JSON

filing.accepted

JSON

remittance.completed

JSON

requirement.satisfied

JSON