Webhooks

Webhooks push real-time events to your server so you don’t have to poll. Use them to react to deposits, transfers, customer creation, and verification state changes.

Add an endpoint

Open Webhooks

In the dashboard, go to Webhooks and click Add endpoint.

Set your URL

Enter an HTTPS URL on your server that can receive POST requests.

Choose events

Subscribe to the events you care about. You can change these any time.

Wallet events

Event	Fires when
`deposit.confirmed`	A deposit is confirmed and credited to your balance.
`transfer.submitted`	The payout provider accepts a transfer for processing.
`transfer.succeeded`	A transfer settles successfully.
`transfer.failed`	A transfer fails terminally and Yara releases the reserved debit.
`transfer.requires_review`	A transfer has an ambiguous or inconsistent outcome and its debit remains reserved.

Transfer lifecycle payloads contain transfer_id, your reference, and the normalized status. Treat REQUIRES_REVIEW as non-terminal. Yara may later reconcile the transfer to SUCCEEDED or FAILED.

Customer events

Event	Fires when
`customer.created`	A customer is ready for verification.
`customer.verification.submitted`	Yara accepts a customer verification submission.
`customer.verification.approved`	A customer verification submission becomes verified.
`customer.verification.information_requested`	A customer verification submission needs more information.
`customer.verification.rejected`	A customer verification submission is rejected.

See Customer webhooks for payload fields and verification-state behavior.

USD virtual-account deposit events

Event	Fires when
`virtual_account.deposit.received`	Yara stores a provider-confirmed USD deposit with customer attribution. No balance credit is implied yet.
`virtual_account.deposit.completed`	Yara credits your general USD merchant balance after deducting the snapshotted Yara fee.
`virtual_account.deposit.reversed`	Yara posts a compensating debit for a previously completed deposit.

These events include the Yara virtual-account, customer, and deposit IDs; gross amount; Yara fee; net merchant credit; normalized status; and timestamps. They do not expose provider fees or provider balance movements. Treat the completed event as the balance-credit notification.

Transfer funding events

Event	Fires when
`transfer.funding.received`	A bank or crypto payment is provider-verified and stored as a transfer-funding receipt.
`transfer.funding.flagged`	A bank or crypto payment needs review because its amount is mismatched or the funding intent was already credited by another exact payment.

Both events contain transfer_id, funding_intent_id, and a merchant-safe receipt snapshot. transfer.funding.received does not mean the payout has already been submitted. A mismatched bank or crypto receipt is followed by transfer.funding.flagged and receives no automatic ledger credit or reservation.

{
  "id": "4a064a83-5e91-5f9f-a17e-e30abb3f20bd",
  "event": "transfer.funding.flagged",
  "data": {
    "transfer_id": "76179a66-8695-47fd-bca4-310eaa816077",
    "funding_intent_id": "0f92c60a-6870-48ba-b589-a5f9c91ac5ec",
    "receipt": {
      "id": "c81427de-2ca1-4d4b-af89-5bdb65764d8c",
      "status": "REQUIRES_REVIEW",
      "method": "BANK_TRANSFER",
      "provider_transaction_id": "palmpay-order-1",
      "received_amount": { "value": "160000", "currency": "NGN" },
      "expected_amount": { "value": "160640", "currency": "NGN" },
      "variance_amount": { "value": "-640", "currency": "NGN" },
      "gross_usd": { "value": "100", "currency": "USD" },
      "fee_usd": { "value": "0.398406", "currency": "USD" },
      "net_usd": { "value": "99.601594", "currency": "USD" },
      "flag": {
        "code": "AMOUNT_MISMATCH",
        "message": "Funding amount does not match the expected amount"
      },
      "received_at": "2026-06-16T03:02:00Z"
    }
  },
  "created_at": "2026-06-16T03:02:01Z"
}

Payload

Every webhook is a JSON POST with an event ID, event name, resource data, and creation time.

{
  "id": "d723cab9-1ad4-4d4d-821f-6704d834d575",
  "event": "deposit.confirmed",
  "data": {
    "deposit_id": "741eec3c-5596-45b6-a88d-3627a236192f",
    "asset": "USDC",
    "chain": "BASE",
    "amount_usd": "100.000000",
    "status": "CONFIRMED",
    "tx_hash": "0x4f5d2d7a2c8a95c3"
  },
  "created_at": "2026-06-16T03:00:00Z"
}

Verify signatures

Each endpoint has a signing secret. Yara signs the exact request body with HMAC-SHA256 and sends the lowercase hexadecimal digest in X-Yara-Signature. Calculate the digest from the raw body before JSON parsing. Compare it to the header using a constant-time comparison. Reject the delivery when the values do not match. Rotate the secret from the dashboard if you suspect it has been exposed.

Inspect delivery history

You can review outbound event history from the API:

curl "https://api.yara.cash/v1/webhook-events?limit=50" \
  --header "x-yara-api-key: $YARA_API_KEY"

{
  "data": [
    {
      "id": "d723cab9-1ad4-4d4d-821f-6704d834d575",
      "event_type": "deposit.confirmed",
      "resource_type": "deposit",
      "resource_id": "741eec3c-5596-45b6-a88d-3627a236192f",
      "payload": {
        "deposit_id": "741eec3c-5596-45b6-a88d-3627a236192f",
        "status": "CONFIRMED"
      },
      "status": "DISPATCHED",
      "created_at": "2026-06-16T03:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 }
}

Best practices

Respond fast. Return a 2xx quickly and do heavy work asynchronously.
Be idempotent. The same event may be delivered more than once — de-duplicate on the event id.
Retry-friendly. Failed deliveries are retried; you can review status in the dashboard or via the endpoint above.

Wallets as a Service

Guides

API reference

Addresses

Balance

Deposits

Transfers

Transactions

Reference data

Status

Webhooks

Add an endpoint

Wallet events

Customer events

USD virtual-account deposit events

Transfer funding events

Payload

Verify signatures

Inspect delivery history

Best practices

​Add an endpoint

​Wallet events

​Customer events

​USD virtual-account deposit events

​Transfer funding events

​Payload

​Verify signatures

​Inspect delivery history

​Best practices

Add an endpoint

Wallet events

Customer events

USD virtual-account deposit events

Transfer funding events

Payload

Verify signatures

Inspect delivery history

Best practices