Events
Every webhook event Harbor sends, grouped by object, with example payloads.
These are the events you can list in a subscription's notification_types. To set up a subscription, see Webhooks.
- Use
*to receive every event. - Use a group, such as
transfer.*, to receive every event in that group. - Each payload has an
eventfield with the event name.
Customer Events
Subscribe to all of them with customer.*.
| Event | Sent when |
|---|---|
customer.agreement.accepted | The Customer accepts the service agreement. |
customer.kyc.verifying | The Customer submits their KYC information, and review starts. |
customer.kyc.verified | The Customer's KYC is approved. |
customer.kyc.rejected | The KYC is rejected because the information is invalid or incomplete. |
customer.kyc.declined | The KYC is declined by compliance review. The Customer can't continue. |
customer.kyc.revoked | A verified Customer's KYC is revoked, for example because documents expired. |
customer.kyc_level.changed | The Customer's level changes, up or down. The payload has the new level. |
customer.rfi.raised | Compliance needs more information from the Customer before they can continue. |
customer.rfi.resolved | The Customer has answered the request for information. |
{
"uuid": "cus_8mlcKk9cN9HjogohJnYHW0dwD6pmFlZnuowUPjLh",
"event": "customer.agreement.accepted",
"object": "customer",
"status": "verified",
"state": "verified",
"type": "individual",
"first_name": "John",
"middle_name": null,
"last_name": "Morgan",
"email": "[email protected]",
"phone_country_code": "US",
"phone_number": "555-555-1234",
"birth_date": "1988-04-15",
"is_bank_account_linkable": true,
"is_card_linkable": true,
"description": "Sample individual customer for the docs.",
"intermediary_fi_reference": null,
"created_at": "2026-10-05T04:55:32+00:00",
"updated_at": "2026-10-05T04:55:51+00:00",
"has_signed_agreement": true,
"agreement_link": null,
"verification_link": null,
"rfi_link": null,
"kyc_level": null
}The payload has the same fields as the Customer object, plus event and kyc_level.
Onboarding Events
For onboarding through the API. Subscribe to all of them with customer_onboarding.*.
| Event | Sent when |
|---|---|
customer_onboarding.submitted | The onboarding is submitted for verification. |
customer_onboarding.action_required | Something needs to be fixed. Correct it and resend with PATCH. |
customer_onboarding.verified | The onboarding is approved. |
customer_onboarding.declined | The onboarding is declined and can't be corrected. |
customer_onboarding.failed | The verification failed because of a provider error. |
Transfer Events
Subscribe to all of them with transfer.*. For what each status means, see Status Definitions.
| Event | Sent when |
|---|---|
transfer.deposit.created | A deposit lands on a Customer's deposit account and creates an on-ramp transfer. Later updates use the transfer.status.* events. |
transfer.status.pending_harbor | The transfer is waiting for Harbor to settle it. |
transfer.status.on_hold | The transfer is on hold, for example for compliance review. |
transfer.status.request_for_information | The transfer needs more information before it can continue. See Transfer RFI. |
transfer.status.completed | The transfer is complete and the funds are settled. |
transfer.status.rejected | The transfer is rejected, for example because of invalid recipient details. |
transfer.status.expired | The transfer wasn't completed in time. |
transfer.status.refunded | The funds didn't reach the recipient and were returned. |
transfer.sub_status.awaiting_settlement | The card or bank payment was authorized, and Harbor is waiting for the bank to settle it. |
transfer.sub_status.cpn_rfi | The payment network needs more information or documents. Sent with transfer.status.request_for_information. See Transfer RFI. |
transfer.sub_status.cpn_rfi_submitted | The answers were submitted and are being reviewed. The status stays request_for_information. |
Use transfer.sub_status.* to receive only the sub-status events. When the sub-status is cleared, no sub-status event is sent. The next transfer.status.* event shows the change.
{
"uuid": "transfer_Tn5n0O5cBNVYN3KwOXMU43PJe3xPmsXZby54gcVJ",
"event": "transfer.status.completed",
"object": "transfer",
"status": "completed",
"sub_status": null,
"type": "on-ramp",
"settlement_strategy": "immediate",
"source_received": true,
"source": {
"asset": "USD",
"amount": "100.08000000"
},
"destination": {
"asset": "USDC",
"chain": "ethereum",
"address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
"address_memo": null,
"is_self_transfer": false,
"beneficiary_name": "Sample Beneficiary",
"amount": "100.00000000",
"transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
"beneficiary_receiving_wallet_type": null,
"beneficiary_institution_name": null
},
"application_transfer_uuid": "docs-webhook-test-1791185747",
"transfer_instructions": {
"account_number": "359946862018",
"routing_number": "021214891",
"bank_name": "Cross River Bank",
"bank_address": "Cross River Bank, 885 Teaneck Rd, Teaneck, NJ 07666",
"account_holder_name": "Jane Doe",
"narrative": "3608349202"
},
"commission": {
"percentage": "0",
"amount": "0.00"
},
"receipt": {
"initial_asset": "USD",
"initial_amount": "100.08000000",
"commission_fee": "0.00",
"harbor_fee": "0.10",
"final_asset": "USDC",
"final_amount": "100.00000000",
"exchange_rate": "0.99930000",
"transaction_hash": "SIMULATED_COMPLETED_GIZUZTIIPJ",
"tracking_number_status": null
},
"meta_data": null,
"crypto_pay_in_expired_at": null,
"created_at": "2026-10-05T07:35:49+00:00",
"updated_at": "2026-10-05T07:36:20+00:00"
}The payload has the same fields as the transfer object, plus event.
Deposit Account Events
Subscribe to all of them with deposit_account.*. See Deposit Accounts.
| Event | Sent when |
|---|---|
deposit_account.activated | The deposit account is ready, and its deposit instructions are available. |
deposit_account.failed | The deposit account couldn't be set up. |
deposit_account.disabled | The deposit account is closed. |
Bank Account Events
Subscribe to all of them with bank_account.*.
| Event | Sent when |
|---|---|
bank_account.micro_deposit.received | An outside bank sends a small test deposit (under USD 1.00) to verify a deposit account. It doesn't create a transfer. |
deposit_account.* doesn't include this event. For the payload and how to handle it, see Micro-deposit Verification.
Wallet Events
Subscribe to all of them with wallet.*. See Wallets.
| Event | Sent when |
|---|---|
wallet.balance.updated | A wallet's balance changes. |
Retired Events
| Event | Replaced by |
|---|---|
customer_onboarding.rejected | customer_onboarding.declined if the onboarding can't be corrected, or customer_onboarding.action_required if it can. A subscription that still lists this event receives nothing for it. |
Updated about 1 month ago