Skip to navigation
Guides

Webhooks

How Shimi notifies you about deposits and payouts, and how to build a safe receiver.
View as Markdown

Shimi sends a POST request to the webhook URL configured for your company (Settings → Webhook in the dashboard). The payload for each event is listed under Webhooks You’ll Receive in the API reference.

Events

Eventdata.sourceSent when
Sub-account creditedSUB_ACCOUNTA customer’s dedicated account receives a transfer
Corporate account creditedCORPORATE_ACCOUNTA corporate sub-account receives a transfer
Virtual account fundedVIRTUAL_ACCOUNTA one-time virtual account is paid
Payout succeededPAYOUTA payout completes
Payout failedPAYOUTA payout fails
Crypto deposit receivedA crypto deposit arrives at one of your addresses

Delivery rules

RuleDetail
Method and bodyPOST, Content-Type: application/json, header User-Agent: ShimiWaaS-Webhook/1.0
DeliveredYour endpoint returns any 2xx within 15 seconds
Not deliveredNon-2xx, timeout, or DNS/TLS/connection error. Logged with your response, no automatic retry
ResendsShimi support can resend a logged delivery with the same payload. Treat webhooks as at-least-once
DepositsOnly sent after Shimi verifies the transfer with the bank, so a deposit webhook is real money already credited
PayoutsEvery payout sends one outcome webhook (success or failed), even if Send Payout already returned 200

Build your receiver like this

1

Acknowledge fast

Return 200 immediately, then process the event asynchronously (for example, put it on a queue).

2

Deduplicate

Use data.sessionId for sub-account and corporate deposits, data.reference for payouts and virtual accounts, and data.txHash for crypto.

3

Match, then act

Look up the reference in your own records before crediting a user or marking an order paid. Ignore events you don’t recognise.

4

Reconcile when in doubt

Confirm state with Check Payout Status, Fetch Virtual Account Transaction or the transaction endpoints.

5

Use HTTPS

Keep your endpoint on HTTPS and keep the URL in the dashboard up to date.

Shimi logs every delivery and your server’s response. Ask Shimi support for the delivery log of any reference.