Webhooks

Much of what the Finance API does finishes after your request returns. A pay-in session converts minutes later. A verification verdict arrives when a reviewer gets to it. A pay-out’s fiat leg settles on the bank’s schedule — and can bounce afterwards. You can poll for all of it, but webhooks are the better answer: register an HTTPS endpoint once, and Venly pushes each state change to you.

What’s worth a webhook

Area	Why polling hurts
Pay-in sessions	There is no endpoint to read a session back — a callback or webhook is the only way to observe it.
Pay-outs	A `201` doesn’t mean sent, and `COMPLETED` can still become `RETURNED` later.
Verification	Verdicts are human-paced; polling a party for hours is wasteful.
Partner-terms consent	Your end customer accepts on their own schedule — there is nothing to poll usefully.
Virtual bank accounts	EUR deposit rails may populate after creation returns.

Registering an endpoint

POST /webhooks

{
  "url": "https://client.example/hooks/venly",
  "name": "Production events",
  "authenticationMethod": {
    "type": "API_KEY",
    "headerName": "X-Webhook-Key",
    "apiKey": "whsec_9f2c41ab7d"
  }
}

The url must be an absolute https:// endpoint — plain HTTP is rejected with 400.

Authenticating the caller

Your endpoint is public, so it needs a way to tell a real Venly delivery from anyone else who found the URL. Pick one method at registration:

API_KEY

Venly injects apiKey into the header you name in headerName. Compare it against your stored value using a constant-time comparison.

BASIC_AUTHENTICATION

Standard HTTP basic auth with username and password.

Secrets (apiKey, password) are write-only. They are accepted on registration and update, and never returned by any read. Store your own copy — if you lose it, you must update the webhook with a new secret rather than recovering the old one.

Testing your endpoint

Once registered, send a ping:

curl -X POST https://api.venlyfinance.com/v1/webhooks/{webhookId}/ping \
  -H "Authorization: Bearer {access_token}"

This queues a synthetic PING event to that one webhook, exercising the real delivery path — including the authentication header your handler expects.

Delivery is asynchronous. A 200 means the ping was accepted for delivery, not that your endpoint received it. Confirm arrival in your own logs.

Updating is a full replacement

PUT /webhooks/{webhookId} replaces the whole configuration — it is not a partial patch. Because secrets are never returned by a read, you cannot fetch the current config, tweak one field, and send it back: the secret would be missing. Always send every field you want to keep, including a complete authenticationMethod. This is also how you rotate a key or password.

What you receive

Every delivery has the same two-field shape — the event type, and an event-specific result:

{
  "eventType": "TRANSFER_COMPLETED",
  "result": {
    "transferId": "9d41f0c7-2b8e-4a15-93cf-6e07ba5d1284",
    "senderAccountId": "4a7c33e1-59db-4f02-8c6a-b1e9d7205fa3",
    "receiverAccountId": "c8e5b204-71fa-4d38-95b7-30a6f8c41de9",
    "asset": "USDC",
    "chain": "BASE",
    "transactionHash": "0x4f7a2c9e18b3d05a6c7e94f120d8b3a5e6f1c07d92b4a8e35f6c1d0b7a92e438",
    "occurredAt": "2026-08-19T09:14:52.318472901ZZ"
  }
}

Two things to build around:

No event carries an amount. This is deliberate. Amounts, balances and bank coordinates stay behind the authenticated REST API — an event tells you what changed, and you read the values back over REST. So a PAYOUT_RETURNED tells you a return happened, not how much came back.

Every webhook receives every event. Registration has no event-type selection, so you cannot narrow what an endpoint gets. Switch on eventType in your handler and ignore what you don’t need.

occurredAt is when the state change happened, not when it was delivered — deliveries typically land one to twenty seconds later, and a retry can arrive much later.

Event catalogue

Thirteen event types:

`eventType`	Fires when	`result` fields
`PING`	You call the test endpoint. Carries no business data.	`message`
`PAY_IN_SETTLED`	A pay-in’s crypto credit is confirmed on-chain and available to the account.	`payInId`, `accountId`, `status`, `asset`, `chain`, `transactionHash`, `occurredAt`
`PAY_IN_FAILED`	A pay-in ended without ever crediting the account. No `PAY_IN_SETTLED` will follow.	`payInId`, `accountId`, `status`, `reason`, `occurredAt`
`TRANSFER_COMPLETED`	An account-to-account transfer settled with the receiving account.	`transferId`, `senderAccountId`, `receiverAccountId`, `asset`, `chain`, `transactionHash`, `occurredAt`
`TRANSFER_FAILED`	A transfer failed terminally. The funds remain with the sender.	`transferId`, `senderAccountId`, `receiverAccountId`, `asset`, `chain`, `reason`, `occurredAt`
`PAYOUT_PROCESSING`	The crypto left the account wallet and reached the banking partner. The send leg can no longer fail.	`payoutId`, `accountId`, `status`, `occurredAt`
`PAYOUT_COMPLETED`	The beneficiary has been paid.	`payoutId`, `accountId`, `status`, `occurredAt`
`PAYOUT_REJECTED`	The pay-out was refused before execution began, so no funds left the account.	`payoutId`, `accountId`, `status`, `reason`, `occurredAt`
`PAYOUT_FAILED`	Execution had already begun and then failed terminally. No money reached the beneficiary.	`payoutId`, `accountId`, `status`, `reason`, `occurredAt`
`PAYOUT_RETURNED`	The receiving bank sent the pay-out back.	`payoutId`, `accountId`, `status`, `reason`, `occurredAt`
`VIRTUAL_BANK_ACCOUNT_CREATED`	The account can now receive deposits.	`virtualBankAccountId`, `accountId`, `status`, `occurredAt`
`ACCOUNT_WALLETS_PROVISIONED`	An account’s wallet pair cleared AML screening and can be used.	`accountId`, `walletPairId`, `walletType`, `chain`, `accountWalletAddress`, `escrowWalletAddress`, `amlStatus`, `occurredAt`
`PARTY_VERIFICATION_COMPLETED`	An individual party’s verification produced an outcome. Read `status` — it is usually `VERIFIED` or `REJECTED`, but `VERIFICATION_PENDING` is also possible, so don’t assume the event means a decision was reached.	`partyId`, `status`, `occurredAt`

Coming to this catalogue: partner-terms acceptance. An event announcing that an end customer has completed partner-terms consent is being added, so you will not have to poll the party to learn that onboarding can proceed. The event type is being finalised — until it lands, read the party back to check its consent state.

Four of these need care:

PAYOUT_REJECTED vs PAYOUT_FAILED — rejected means nothing was ever sent; failed means execution started and then broke. Only the second can leave a pay-out needing investigation.
PAYOUT_RETURNED does not imply an earlier PAYOUT_COMPLETED. A return can be reported while the pay-out is still processing, so never treat it as a correction to a completion you must have received.
VIRTUAL_BANK_ACCOUNT_CREATED fires on readiness, not on creation. The resource exists earlier, without usable bank coordinates. This event means deposits will now land.
PARTY_VERIFICATION_COMPLETED fires on every verdict, including a re-verification of the same party. Others are keyed per resource, so a second delivery for the same resource is a duplicate; this one may be genuinely new.

Event payloads

Transfers

Crypto and fiat-originated transfers publish the same event with an identical payload — nothing reveals which one it was.

TRANSFER_COMPLETED

{
  "eventType": "TRANSFER_COMPLETED",
  "result": {
    "transferId": "9d41f0c7-2b8e-4a15-93cf-6e07ba5d1284",
    "senderAccountId": "4a7c33e1-59db-4f02-8c6a-b1e9d7205fa3",
    "receiverAccountId": "c8e5b204-71fa-4d38-95b7-30a6f8c41de9",
    "asset": "USDC",
    "chain": "BASE",
    "transactionHash": "0x4f7a2c9e18b3d05a6c7e94f120d8b3a5e6f1c07d92b4a8e35f6c1d0b7a92e438",
    "occurredAt": "2026-08-19T09:14:52.318472901ZZ"
  }
}

TRANSFER_FAILED

{
  "eventType": "TRANSFER_FAILED",
  "result": {
    "transferId": "7b02ea56-c3d9-4718-8f45-2ac6be901f37",
    "senderAccountId": "4a7c33e1-59db-4f02-8c6a-b1e9d7205fa3",
    "receiverAccountId": "e1f7d9a3-46b2-4c85-91da-587c0e2b6d34",
    "asset": "EURC",
    "chain": "AVALANCHE",
    "reason": "INSUFFICIENT_ALLOWANCE",
    "occurredAt": "2026-08-19T09:21:07.664215330ZZ"
  }
}

reason is one of ON_CHAIN_FAILED, INSUFFICIENT_FUNDS, INSUFFICIENT_ALLOWANCE, NOT_SUBMITTED, UNKNOWN.A failed transfer has no transactionHash when it never reached the chain (NOT_SUBMITTED).

Pay-outs

A pay-out publishes up to two events: one when it reaches the banking partner, and one for its outcome.

PAYOUT_PROCESSING

{
  "eventType": "PAYOUT_PROCESSING",
  "result": {
    "payoutId": "5c8fd317-a094-42be-b6e1-7d3f02951ac8",
    "accountId": "83b16e40-df75-4a29-9c03-e5a18427bd6f",
    "status": "PROVIDER_PROCESSING",
    "occurredAt": "2026-08-19T10:02:41.127903558ZZ"
  }
}

PAYOUT_COMPLETED

{
  "eventType": "PAYOUT_COMPLETED",
  "result": {
    "payoutId": "5c8fd317-a094-42be-b6e1-7d3f02951ac8",
    "accountId": "83b16e40-df75-4a29-9c03-e5a18427bd6f",
    "status": "COMPLETED",
    "occurredAt": "2026-08-19T10:05:18.844061272ZZ"
  }
}

PAYOUT_RETURNED

{
  "eventType": "PAYOUT_RETURNED",
  "result": {
    "payoutId": "a0d64b98-31ce-4f27-85ba-c9147e0d2f63",
    "accountId": "83b16e40-df75-4a29-9c03-e5a18427bd6f",
    "status": "RETURNED",
    "reason": "RETURNED_BY_BANK",
    "occurredAt": "2026-08-19T10:11:33.209774615ZZ"
  }
}

PAYOUT_REJECTED and PAYOUT_FAILED have the same shape as PAYOUT_RETURNED, with status REJECTED or FAILED.reason is one of REJECTED_BY_PROVIDER, ROUTE_UNAVAILABLE, SEND_FAILED, RETURNED_BY_BANK, UNKNOWN.

The reason is a fixed enum, never free text. Operational notes recorded against a pay-out internally are not delivered — if you need more detail than the enum, read the pay-out back.

Pay-ins

PAY_IN_SETTLED

{
  "eventType": "PAY_IN_SETTLED",
  "result": {
    "payInId": "b3719ce5-8f24-4d60-a917-4c8e05f2d6b1",
    "accountId": "62ad8f14-70e3-49c5-b8f2-1d90ae637c05",
    "status": "SETTLED",
    "asset": "USDC",
    "chain": "BASE",
    "transactionHash": "0xa19c47f2e8b06d35c1f7094ae2b8d5306f4c19e7ad025b8f3c6019e74bd2f581",
    "occurredAt": "2026-08-19T11:37:09.552840173ZZ"
  }
}

PAY_IN_FAILED

{
  "eventType": "PAY_IN_FAILED",
  "result": {
    "payInId": "d5e8017b-49ac-4f31-96b0-8a27ce4f10d3",
    "accountId": "62ad8f14-70e3-49c5-b8f2-1d90ae637c05",
    "status": "FAILED",
    "reason": "REJECTED_BY_PROVIDER",
    "occurredAt": "2026-08-19T11:44:26.981037462ZZ"
  }
}

reason is one of SETTLEMENT_FAILED, REJECTED_BY_PROVIDER, UNKNOWN.A PAY_IN_FAILED is terminal for that pay-in — no PAY_IN_SETTLED will follow it.

Onboarding

ACCOUNT_WALLETS_PROVISIONED

{
  "eventType": "ACCOUNT_WALLETS_PROVISIONED",
  "result": {
    "accountId": "18fc6a92-b537-4e08-91d4-cb70a3f5e264",
    "walletPairId": "7e3d0b85-1a4f-4926-83c7-59d2e0148fab",
    "walletType": "VENLY_MANAGED",
    "chain": "AVALANCHE",
    "accountWalletAddress": "0x6D3fA92c15E0847bB1de5C90a7F328e4051cB7d9",
    "escrowWalletAddress": "0xB84e07f1cA935D620387be4dF16c8a0952E7d34C",
    "amlStatus": "APPROVED",
    "occurredAt": "2026-08-19T08:52:14.703918046ZZ"
  }
}

This is the one event that carries on-chain addresses — they are the point of it. One event per wallet pair, not per account.

PARTY_VERIFICATION_COMPLETED

{
  "eventType": "PARTY_VERIFICATION_COMPLETED",
  "result": {
    "partyId": "2f95c8e0-6b71-4a3d-8e14-07db5c9f2a68",
    "status": "VERIFIED",
    "occurredAt": "2026-08-19T13:26:55.410682937ZZ"
  }
}

status is VERIFIED, REJECTED, or VERIFICATION_PENDING. The verdict and nothing else — no reasons, documents, or personal data. A rejection tells you the outcome, not why.

VIRTUAL_BANK_ACCOUNT_CREATED

{
  "eventType": "VIRTUAL_BANK_ACCOUNT_CREATED",
  "result": {
    "virtualBankAccountId": "4c1e73d9-a825-4b06-97fe-3d6082ca4157",
    "accountId": "62ad8f14-70e3-49c5-b8f2-1d90ae637c05",
    "status": "ACTIVE",
    "occurredAt": "2026-08-19T12:08:47.336529814ZZ"
  }
}

The bank coordinates are not in the event. Read them from Get a virtual bank account once this arrives.

Ping

PING

{
  "eventType": "PING",
  "result": { "message": "ping" }
}

Sent only by the ping endpoint. Handle it as a no-op, but do return 2xx — it is how you prove your endpoint works.

Writing a handler

A few rules that hold regardless of which events you subscribe to:

Verify before you trust

Check the authentication header first and reject anything that fails, before parsing the body.

Respond fast, work later

Acknowledge with a 2xx immediately and hand the payload to a queue. Slow handlers look like failures to any delivery system.

Expect duplicates

Treat delivery as at-least-once — retries do happen in practice. Key your processing on the event’s resource id plus target status so a repeat is a no-op — for a second delivery of TRANSFER_COMPLETED, the transferId is already COMPLETED on your side and there is nothing to do. Same discipline as idempotency on the request side.

Don't assume ordering

A later state can arrive before an earlier one, so compare against the state you already hold.

Do not simply discard anything that looks like a step backwards. Some transitions legitimately reverse an outcome — a pay-out can go COMPLETED → RETURNED when the receiving bank sends it back, sometimes long afterwards. Decide per event type which transitions are real, rather than ordering states and dropping everything below the high-water mark.

Re-read the resource for anything that matters

For money movement, treat the event as a hint that something changed and confirm against the API — for example Get a payout — before crediting a ledger or releasing goods.

Managing registrations

Operation	Endpoint
List all	`GET /webhooks` — not paginated
Read one	`GET /webhooks/{webhookId}`
Replace	`PUT /webhooks/{webhookId}`
Remove	`DELETE /webhooks/{webhookId}`

Registering requires the manage:webhooks role; reading requires view:webhooks. There is a per-company cap on registered webhooks — exceeding it returns 409. If you need more endpoints than the cap allows, fan out on your own side from a single receiver.

Webhook delivery is handled by Venly. A 503 on any of these endpoints means that service was briefly unreachable, not that your registration is broken — retry with backoff.

Next steps

Pay-outs

Where webhooks matter most — a 201 isn’t a success signal.

Idempotency

The request-side counterpart to duplicate-tolerant handlers.

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Reference

Webhooks

What’s worth a webhook

Registering an endpoint

Authenticating the caller

API_KEY

BASIC_AUTHENTICATION

Testing your endpoint

Updating is a full replacement

What you receive

Event catalogue

Event payloads

Writing a handler

Managing registrations

Next steps

Pay-outs

Idempotency

​What’s worth a webhook

​Registering an endpoint

​Authenticating the caller

API_KEY

BASIC_AUTHENTICATION

​Testing your endpoint

​Updating is a full replacement

​What you receive

​Event catalogue

​Event payloads

​Writing a handler

​Managing registrations

​Next steps

Pay-outs

Idempotency

What’s worth a webhook

Registering an endpoint

Authenticating the caller

Testing your endpoint

Updating is a full replacement

What you receive

Event catalogue

Event payloads

Writing a handler

Managing registrations

Next steps