> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Complete reference for all webhook event types available in Fyatu CaaS API v3.20.

## Overview

All webhook deliveries share a common JSON envelope. Register for specific event types when [creating a webhook endpoint](https://docs.fyatu.com/v3.20/api-reference/webhooks/create.md).

```json theme={null}
{
  "event":       "CARD_AUTHORIZATION",
  "eventId":     "EVTJHLTPQH45SAP",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-27T14:32:00Z",
  "data": {
    // Event-specific fields
  }
}
```

## Signature Verification

Each request carries an `X-Fyatu-Signature` header in the format `t=<unix_timestamp>,v1=<hex_hmac>`. The HMAC is SHA-256 over `"<timestamp>.<raw_request_body>"` using your webhook signing secret as the key.

```javascript Node.js theme={null}
const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const [tPart, v1Part] = signatureHeader.split(',');
  const timestamp = tPart.replace('t=', '');
  const receivedHmac = v1Part.replace('v1=', '');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac, 'hex'),
    Buffer.from(expected, 'hex')
  );
}
```

Reject any delivery where verification fails or the timestamp is older than 5 minutes.

***

## Account Events

| Event | Trigger |
| - | - |
| `ACCOUNT_LOW_BALANCE` | Program balance has dropped below the configured low-balance threshold |
| `ACCOUNT_WITHDRAWAL_INITIATED` | A crypto withdrawal from your program balance was requested |
| `ACCOUNT_WITHDRAWAL_COMPLETED` | The crypto withdrawal was sent on chain. Carries `transactionHash` |
| `ACCOUNT_WITHDRAWAL_FAILED` | The crypto withdrawal could not be completed. The amount is returned to your program balance |

### Withdrawal payloads

All three carry `withdrawalId`, `programId`, `amount`, `token`, `network` and `toAddress`.

| Event | Additional fields |
| - | - |
| `ACCOUNT_WITHDRAWAL_COMPLETED` | `transactionHash` — the on-chain hash; `netAmount` — the amount sent after fees |
| `ACCOUNT_WITHDRAWAL_FAILED` | `refunded` — `true` when the amount is back in your balance |

> [!NOTE]
>
> `transactionHash` cannot be known when a withdrawal is accepted, because nothing has been
> broadcast at that point. Expect `ACCOUNT_WITHDRAWAL_INITIATED` without a hash, and
> `ACCOUNT_WITHDRAWAL_COMPLETED` with one, some time later.

***

## Billing Events

| Event | Trigger |
| - | - |
| `BILLING_INVOICE_CREATED` | A new invoice was generated (monthly subscription or program setup) |
| `BILLING_INVOICE_PAID` | An invoice was fully paid via crypto deposit |
| `BILLING_INVOICE_OVERDUE` | An invoice passed its due date without payment |
| `BILLING_DEPOSIT_DETECTED` | A deposit to one of your addresses was recorded and attributed to your program. Nothing has been credited yet |
| `BILLING_DEPOSIT_CONFIRMED` | The deposit was credited to your program balance |

### Deposit payloads

Both deposit events carry the chain detail, so a transfer can be reconciled against a block
explorer without asking us anything:

| Field | Notes |
| - | - |
| `depositId` | Our identifier for the deposit |
| `transactionHash` | The on-chain transaction hash |
| `fromAddress` | The address the funds were sent from |
| `toAddress` | Your deposit address that received them |
| `token` / `network` | The asset and the chain, e.g. `USDT` on `BEP20` |
| `amountOnChain` | What the chain moved, before our deposit fee. A **string**, so a token amount with many decimal places is not rounded in transit |
| `amount` | The amount applied to your account, in USD |
| `balance` | Your program balance after crediting (`BILLING_DEPOSIT_CONFIRMED` only) |
| `confirmations` | Included when a confirmation count was recorded for the transfer |

`DETECTED` carries no `balance`, because nothing has been credited at that point. A field is
omitted rather than sent empty when we do not hold it.

> [!NOTE]
>
> `BILLING_DEPOSIT_CONFIRMED` means the deposit reached your balance. Do not read it as
> "N confirmations observed"; use `transactionHash` to check the transfer on a block explorer.

***

## Cardholder Events

| Event | Trigger |
| - | - |
| `CARDHOLDER_CREATED` | A new cardholder was created under your program |
| `CARDHOLDER_SUSPENDED` | A cardholder was suspended — all their cards are frozen |
| `CARDHOLDER_REACTIVATED` | A suspended cardholder was reactivated |
| `CARDHOLDER_DELETED` | A cardholder was permanently deleted |
| `CARDHOLDER_KYC_APPROVED` | KYC verification was approved — cardholder can now be issued cards |
| `CARDHOLDER_KYC_REJECTED` | KYC verification was rejected |

***

## Card Events

| Event | Trigger |
| - | - |
| `CARD_ISSUED` | A new card was issued to a cardholder |
| `CARD_FROZEN` | A card was frozen |
| `CARD_UNFROZEN` | A frozen card was unfrozen |
| `CARD_TERMINATED` | A card was permanently terminated |
| `CARD_STATUS_CORRECTED` | A card's status was corrected to match the card issuer — the status we previously reported was wrong |
| `CARD_TERMINATION_REFUND` | A terminated card's remaining balance was refunded to your program |
| `CARD_TERMINATION_REFUND_POST` | Funds arrived on an already-terminated card (discrepancy or merchant refund) and were refunded to your program — may fire multiple times per card |
| `CARD_FUNDED` | Balance was added to a card |
| `CARD_UNLOADED` | Balance was removed from a card |
| `CARD_FUND_FAILED` | A card funding attempt failed |
| `CARD_UNLOAD_FAILED` | A card unload attempt failed |
| `CARD_NEGATIVE_BALANCE` | A card's balance dropped below zero — `amount` is what it owes |
| `CARD_NEGATIVE_BALANCE_SETTLED` | A card that was below zero is back to zero or above |
| `CARD_LIMITS_UPDATED` | A card's spending/velocity limits were updated |
| `CARD_LIMITS_UPDATE_FAILED` | A card limits update attempt failed |
| `CARD_3DS_OTP` | A 3D Secure authentication code was generated — deliver to cardholder immediately |
| `CARD_TOKENIZATION_OTP` | A digital wallet tokenization code was generated — deliver to cardholder immediately |
| `CARD_AUTHORIZATION` | An authorization decision was made (approved or declined) |

***

## Transaction Events

| Event | Trigger |
| - | - |
| `TRANSACTION_PROCESSED` | A card transaction was processed. The `status` field carries the outcome — `COMPLETED`, `REVERSED`, or `ADJUSTED`. |
| `TRANSACTION_DECLINED` | A card authorization was declined |
| `TRANSACTION_FEE` | A transaction fee (e.g. FX, decline, cross-border) was applied to a card |

`TRANSACTION_PROCESSED` is the single event for the card-charge lifecycle. A card
charge is delivered as one event with `status: COMPLETED` (or `REVERSED` when the
charge was reversed/refunded, `ADJUSTED` for an FX settlement adjustment). There is
no separate authorization-then-settlement pair — subscribe to `TRANSACTION_PROCESSED`
and branch on `status`.

```json TRANSACTION_PROCESSED payload theme={null}
{
  "event": "TRANSACTION_PROCESSED",
  "eventId": "EVTJHLTPQH45SAP",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp": "2026-06-21T16:05:00Z",
  "data": {
    "transactionId": "TXN7K2P9QX4ABCD",
    "cardId": "CRD5N8M2VBQ1WXYZ",
    "cardholderId": "CDH9A1B2C3D4E5F6",
    "externalId": null,
    "type": "PURCHASE",
    "status": "COMPLETED",
    "amount": 20.00,
    "currency": "USD",
    "billingAmount": 20.00,
    "billingCurrency": "USD",
    "merchant": {
      "name": "OPENAI *CHATGPT SUBSCR",
      "country": "US",
      "mcc": "5734"
    }
  }
}
```

> [!NOTE]
>
> **Deprecated transaction events.** `TRANSACTION_AUTHORIZED`, `TRANSACTION_CLEARED`,
> and `TRANSACTION_REVERSED` are deprecated in favor of `TRANSACTION_PROCESSED`. They
> remain fully supported — existing integrations subscribed to them continue to
> receive deliveries unchanged, so no action is required. New integrations should
> subscribe to `TRANSACTION_PROCESSED`.

***

## Delivery & Retry Policy

| Property | Value |
| - | - |
| Timeout | 30 seconds per attempt |
| Max attempts | 5 |
| Retry schedule | 1 min → 5 min → 30 min → 2 h → 24 h |
| Success criteria | HTTP 2xx |

Return `200 OK` immediately and process the webhook asynchronously. Slow handlers that exceed the timeout trigger retries, which may cause duplicate processing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.