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

# Webhooks overview

> How Sakawave tells you something happened — the envelope, the headers, and the one delivery attempt you get.

Most of what matters in this API happens after your request returns. A transfer settles, a card is authorised, a bill is vended, an account becomes payable. Webhooks are how you find out.

## One endpoint, every event

A business has **one** active webhook endpoint per environment, and it receives **every** event for that business. There is no per-event subscription and no filtering — route on the `event` field and ignore what you do not handle.

The endpoint is configured in the dashboard. There is no `/v1` endpoint for managing it.

## The envelope

Every request body has exactly two fields.

```json theme={null}
{
  "event": "fiat.withdrawal.completed",
  "data": {}
}
```

That is the whole envelope. **There is no `id`, no `version`, no `environment`, and no `createdAt` in the body.** Everything else travels as headers:

| Header | Meaning |
| - | - |
| `Sakawave-Webhook-Id` | The stable event identifier. **Deduplicate on this.** |
| `Sakawave-Webhook-Timestamp` | Unix seconds for this attempt. Part of the signed value. |
| `Sakawave-Webhook-Signature` | `v1=` followed by the hexadecimal HMAC-SHA-256. |
| `Sakawave-Webhook-Attempt` | One-based attempt number. |

<Warning>
  The body carries no identifier. A handler that deduplicates on `data.id` is deduplicating on a business object, not an event — and will drop a legitimate second event about the same object.
</Warning>

## Two payload families

| Family | `data` is | Events |
| - | - | - |
| **Financial** | The posted ledger transaction, with the movement in `relatedOperation` | `fiat.*`, `bills_payment.*`, `card.transaction.*` |
| **Resource** | The same object the REST endpoint returns | `account.*`, `card.*`, `customer.*` |

A financial payload tells you money moved and what it was for. A resource payload is a snapshot of an object, identical to what a `GET` would give you.

See [webhook events](/webhooks/events) for the full catalog and both shapes.

## One attempt

This is the most important operational fact about Sakawave webhooks.

<Warning>
  Delivery is **a single attempt**. There is no automatic retry and no backoff. A delivery that fails — a timeout, a `500`, a connection reset — is marked exhausted, and the only recovery is a manual resend from the dashboard or your own reconciliation.
</Warning>

That has a direct consequence: **webhooks are a latency optimisation, not a source of truth.** Any flow where missing an event would cost money needs a reconciliation job reading the REST resources.

| | Webhooks | Reconciliation |
| - | - | - |
| Latency | Seconds | Minutes to hours |
| Guaranteed | No | Yes |
| Use for | Reacting quickly | Being correct |

## The delivery contract

```mermaid theme={null}
flowchart LR
    E["Event staged<br/>in the same transaction<br/>as the business write"] --> D["One POST<br/>10s timeout"]
    D -->|2xx| OK["delivered"]
    D -->|anything else| X["exhausted<br/>manual resend only"]
```

1. Read the **raw** body. Do not parse it first.
2. Verify the signature and a narrow timestamp window.
3. Deduplicate on `Sakawave-Webhook-Id`, atomically with recording receipt.
4. Queue the work.
5. Return any `2xx` within **ten seconds**.

Sakawave does not follow redirects. Keep the endpoint public over HTTPS and authenticate every request by its signature, never by network position.

## Next

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/webhooks/introduction">
    What to use webhooks for, and what not to.
  </Card>

  <Card title="Get started" icon="play" href="/webhooks/get-started">
    A receiver that verifies, deduplicates, and acknowledges.
  </Card>

  <Card title="Events" icon="list" href="/webhooks/events">
    The catalog and both payload shapes.
  </Card>

  <Card title="Verify signatures" icon="shield" href="/webhooks/verify-signatures">
    Complete handlers in Node and Python.
  </Card>
</CardGroup>


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