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

# Webhooks

> How FYATU tells your server that something happened: subscribing, verifying the signature, answering, retries, and handling an event more than once.

Most of what matters happens after your request returns: a card finishes provisioning, a funding is
confirmed, a cardholder is verified, a purchase is approved. A **webhook** is how you hear about it:
FYATU sends an HTTPS `POST` to your server for every event you subscribed to.

Build on webhooks rather than polling: polling spends your [rate limit](https://docs.fyatu.com/v3.20/documentation/rate-limits.md),
and a webhook reaches you as soon as the event happens.

## Subscribing

Register an endpoint with the events it should receive:

```bash theme={null}
curl -X POST https://api.fyatu.com/api/v3.20/webhooks \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourcompany.com/webhooks/fyatu",
    "events": [
      "CARD_ISSUED",
      "CARD_FUNDED",
      "CARD_FUND_FAILED",
      "CARDHOLDER_KYC_APPROVED",
      "CARDHOLDER_KYC_REJECTED",
      "TRANSACTION_PROCESSED",
      "TRANSACTION_DECLINED"
    ]
  }'
```

* The response carries the endpoint's signing **`secret`**, shown **once**. Store it now.
* A live endpoint must use `https://`, and it cannot point at a private or internal address.
* Up to **10 endpoints** per business. One endpoint may take every event.
* An endpoint receives the events of its own environment: sandbox events go to sandbox endpoints.
* `GET /event-types` returns every event you can subscribe to, and the
  [event list](https://docs.fyatu.com/v3.20/api-reference/webhooks/events) describes each one; every event also has its own
  page under **Webhooks**.

Manage endpoints with [`GET`](https://docs.fyatu.com/v3.20/api-reference/webhooks/list), [`PATCH`](https://docs.fyatu.com/v3.20/api-reference/webhooks/update)
and [`DELETE /webhooks/{id}`](https://docs.fyatu.com/v3.20/api-reference/webhooks/delete). Sending a test event, resending a
delivery, rotating the secret and reading the delivery history are in the CaaS portal under
**Developers → Webhooks**.

## What a delivery looks like

```http theme={null}
POST /webhooks/fyatu HTTP/1.1
Content-Type: application/json
User-Agent: Fyatu-Webhook/3.20
X-Fyatu-Event: CARD_FUNDED
X-Fyatu-Event-ID: evt_01HXY123456ABCDEF
X-Fyatu-Delivery: wdl_01HXY987654FEDCBA
X-Fyatu-Environment: LIVE
X-Fyatu-Timestamp: 1763215200
X-Fyatu-Signature: t=1763215200,v1=5c0f...

{
  "event":       "CARD_FUNDED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-11-15T14:00:00Z",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        50.00,
    "currency":      "USD",
    "reference":     "order-001",
    "transactionId": "ltx_01HXYZ9999ABCDEF2222"
  }
}
```

`event` names the event and `data` carries its details; each event's page documents its `data`.

## Verifying the signature

Every delivery is signed with your endpoint's secret, so you can prove it came from FYATU and was not
altered. Verify it on the **raw** request body, before parsing it, and reject anything that fails:

1. Read `t` and `v1` from `X-Fyatu-Signature`.
2. Derive the signing key: the SHA-256 hex digest of your secret.
3. Compute HMAC-SHA256 of `"{t}.{raw body}"` with that key, and compare it with `v1` in constant time.
4. Reject a `t` more than a few minutes old, so an intercepted delivery cannot be replayed later.

[Signature Verification](https://docs.fyatu.com/v3.20/webhooks/signature-verification.md) has the code in Node.js, Python,
PHP, Go and Ruby.

## Answering

* Answer **`2xx` within 30 seconds**. Anything else counts as a failure.
* Answer first, then do the work: store the event and process it in the background, so a slow
  database or a third-party call never makes you miss the deadline.
* The response body is ignored.

## Retries

A delivery your endpoint answers with a non-`2xx` status is tried **5 times** in all: at once, then
after 15 seconds, 2 minutes, 15 minutes and 1 hour.

A delivery that gets no answer at all — your endpoint refuses the connection, its host name does not
resolve, or it does not answer within 30 seconds — is retried on the same schedule. The delivery log
in **Developers → Webhooks** shows why each attempt failed, and anything that ran out of attempts can
be resent from there.

> [!WARNING]
>
> An endpoint on a private or internal address (loopback, private ranges, link-local, cloud
> metadata) is refused when you save it, with `422 WEBHOOK_URL_BLOCKED`, and is never delivered to.

## Handling an event twice, or out of order

Delivery is **at least once**. The same event can arrive more than once, for example when we retry
after your server processed it but answered late, or when a delivery is resent.

* Deduplicate on `X-Fyatu-Event-ID` (the `eventId` in the body). It is the same on every retry and
  resend of one event; `X-Fyatu-Delivery` changes with each attempt.
* Do not rely on order. A `CARD_FUNDED` can arrive before the `CARD_ISSUED` it follows. Treat each
  event as "this happened", and read the resource with the API when you need its current state.

## Which events to start with

| You want to know when… | Subscribe to |
| - | - |
| A cardholder can be issued cards | `CARDHOLDER_KYC_APPROVED`, `CARDHOLDER_KYC_REJECTED` |
| A card is ready | `CARD_ISSUED` |
| A funding or unload went through | `CARD_FUNDED`, `CARD_FUND_FAILED`, `CARD_UNLOADED`, `CARD_UNLOAD_FAILED` |
| A cardholder spent, or was declined | `TRANSACTION_PROCESSED`, `TRANSACTION_DECLINED` |
| A closed card's balance came back | `CARD_TERMINATION_REFUND` |
| A card's status was corrected | `CARD_STATUS_CORRECTED` |
| A 3D Secure code must reach the cardholder | `CARD_3DS_OTP` |
| Your balance is running low | `ACCOUNT_LOW_BALANCE` |

## Endpoints

* [`POST /webhooks`](https://docs.fyatu.com/v3.20/api-reference/webhooks/create), [`GET /webhooks`](https://docs.fyatu.com/v3.20/api-reference/webhooks/list), [`GET /webhooks/{id}`](https://docs.fyatu.com/v3.20/api-reference/webhooks/get), [`PATCH /webhooks/{id}`](https://docs.fyatu.com/v3.20/api-reference/webhooks/update), [`DELETE /webhooks/{id}`](https://docs.fyatu.com/v3.20/api-reference/webhooks/delete)
* `GET /event-types`, with the [event list](https://docs.fyatu.com/v3.20/api-reference/webhooks/events)


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