deposit.* webhook when money arrives into one of your customers’
accounts — a bank transfer into a virtual account, or a crypto transfer into a
deposit address. Money landing in an account is a deposit event, not an account
event.
All three events:
- relate to one deposit, so
data.idis itsdep_…id anddata.customerIdis the owning customer’scus_…id - use the standard envelope, signature and retry rules from the Webhooks guide
"eventFilter": ["deposit.*"] to receive all of them.
Payload fields
Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change.
The payload has no currency or account field. Match the deposit to the
customer with
data.customerId, and take the currency from the account the funds
were sent to.Rails
Treat the list as open-ended: new rails can appear.
Typical lifecycle
deposit.createdis optional. Many deposits, crypto ones especially, are only seen once they have landed, sodeposit.receivedcan be the first and only event.- The pending state sends nothing. A deposit in
PENDINGemits no event; the next one you get isdeposit.receivedordeposit.failed. - The partner’s own funding is excluded. Deposits into your own POBO funding account are not customer deposits and emit no event.
- Order isn’t guaranteed across retries. A late
deposit.createdmust never overwrite a deposit you already marked as received.
Events in detail
deposit.created
When: the deposit has been seen and authorised by the receiving rail but not yet credited. What to do: show the money as incoming. Don’t release goods or credit a balance yet.deposit.received
When: the funds have been credited to the customer’s account. Final. What to do: credit the customer in your own ledger, usingamountReceived.
"rail": "CRYPTO":
deposit.failed
When: the deposit was cancelled before it was credited, for example because the sending bank recalled it. Final. What to do: remove the incoming amount you showed ondeposit.created.
Best practices
- Verify the signature, then deduplicate on
eventId, then act. Delivery is at least once, so the same event can arrive twice. - Credit only on
deposit.received.deposit.createdmeans “on its way”, not “arrived”. - Treat
receivedandfailedas final. Ignore any laterdeposit.createdfor the samedep_id. - Subscribe with
deposit.*so you automatically receive new deposit events Endl adds later.