> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.shimi.cash/webhooks/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.shimi.cash/_mcp/server.

# Webhooks

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](/api-reference).

## Events

| Event                      | `data.source`       | Sent when                                          |
| -------------------------- | ------------------- | -------------------------------------------------- |
| Sub-account credited       | `SUB_ACCOUNT`       | A customer's dedicated account receives a transfer |
| Corporate account credited | `CORPORATE_ACCOUNT` | A corporate sub-account receives a transfer        |
| Virtual account funded     | `VIRTUAL_ACCOUNT`   | A one-time virtual account is paid                 |
| Payout succeeded           | `PAYOUT`            | A payout completes                                 |
| Payout failed              | `PAYOUT`            | A payout fails                                     |
| Crypto deposit received    |                     | A crypto deposit arrives at one of your addresses  |

## Delivery rules

| Rule            | Detail                                                                                                         |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| Method and body | `POST`, `Content-Type: application/json`, header `User-Agent: ShimiWaaS-Webhook/1.0`                           |
| Delivered       | Your endpoint returns **any 2xx within 15 seconds**                                                            |
| Not delivered   | Non-2xx, timeout, or DNS/TLS/connection error. Logged with your response, **no automatic retry**               |
| Resends         | Shimi support can resend a logged delivery with the same payload. Treat webhooks as **at-least-once**          |
| Deposits        | Only sent after Shimi verifies the transfer with the bank, so a deposit webhook is real money already credited |
| Payouts         | Every payout sends one outcome webhook (`success` or `failed`), even if Send Payout already returned `200`     |

## Build your receiver like this

### Acknowledge fast

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

### Deduplicate

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

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

### Reconcile when in doubt

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

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

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