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

# Webhooks overview

> Event-driven updates — the 10 events, delivery guarantees, and when to pair webhooks with polling.

Webhooks are the real-time channel. Subscribe once, receive signed POSTs
as the state you care about changes, never poll for that dimension again.

## What you subscribe to

Ten events, grouped by domain. See [event catalog](/webhooks/event-catalog)
for full payload schemas.

| Event                              | What it means                                       |
| ---------------------------------- | --------------------------------------------------- |
| `compliance.status_changed`        | Order rollup transitioned (INCOMPLETE → VALID → …). |
| `compliance.decision_made`         | Final verdict (VALID\_EXPORT or VAT\_APPLICABLE).   |
| `kyc.vies_check_failed`            | Known-good buyer became VIES-invalid. Urgent.       |
| `kyc.verification_completed`       | Mode B iDenfy + AML outcome.                        |
| `export_file.generated`            | Export File PDF ready for download.                 |
| `prospect.submitted`               | New prospect via public self-service link.          |
| `self_service_invitation.used`     | Buyer completed emailed self-service flow.          |
| `self_service_invitation.expired`  | Invitation TTL elapsed unused.                      |
| `webhook.endpoint_auto_paused`     | Meta — your endpoint was paused after failures.     |
| `webhook.delivery_failed_terminal` | Meta — single event exhausted retries.              |

## Delivery guarantees

* **At-least-once.** Deduplicate on event `id`.
* **HMAC-SHA256 signed.** Always verify `X-Novatrade-Signature`.
* **Retries:** 10 attempts over 72h with exponential backoff.
* **Auto-pause:** endpoint paused after 20 consecutive failures OR 72h of
  continuous failure.
* **30-day retention** on delivery history with manual replay.

See [Webhook setup](/webhooks/setup) for registration and
[Signature verification](/webhooks/signature-verification) for the HMAC
check.

## Scoping

Subscriptions support:

* **Exact event types** — `compliance.status_changed`.
* **Segment wildcards** — `compliance.*`, `kyc.*`, `self_service_invitation.*`.
* **Per-partner filter** — `partnerIds` array limits deliveries to
  specific authorized partners; `null` = all.

No root wildcard (`*`) — you must opt in at least at the segment level.

## Envelope shape

Every event body follows the same envelope:

```json theme={null}
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "compliance.status_changed",
  "schemaVersion": 1,
  "source": "SYSTEM",
  "createdAt": "2026-04-22T10:30:00Z",
  "organizationUuid": "550e8400-...",
  "partnerUuid": "11111111-...",
  "data": { /* event-specific payload */ }
}
```

* `id` — for dedup.
* `type` — routing key.
* `schemaVersion` — bump when we evolve the `data` shape. Register the
  versions you accept with `acceptedSchemaVersions`.
* `source` — `API` | `WEB_APP` | `SYSTEM`. Filter self-echoes by
  comparing your own calls against `source=WEB_APP` events.
* `organizationUuid` / `partnerUuid` — route events to the right downstream
  tenant/dealer.
* `data` — see per-event schemas in the [event catalog](/webhooks/event-catalog).

## Webhooks + polling together

Production integrations combine both:

* **Webhooks** minimize latency on reaction to state changes.
* **Polling compliance rollup** reconciles cases where webhook delivery
  was delayed or misrouted. Cheap via `ETag` / `If-None-Match`.

Treat webhooks as a performance optimization over the rollup, not as the
sole source of truth.

## What webhooks do NOT fire on

Customer-initiated actions do not echo back. If you `POST /transport/pickup`,
you already know the pickup was confirmed. No webhook fires for `source=API`
transitions.

Phase 3+ will add `source=WEB_APP`-filtered events for cross-channel sync
(web-app staff confirmed pickup, API caller learns).

## Next

<CardGroup cols={2}>
  <Card title="Setup" icon="plug" href="/webhooks/setup">
    Register an endpoint.
  </Card>

  <Card title="Event catalog" icon="list" href="/webhooks/event-catalog">
    Full payload schemas.
  </Card>
</CardGroup>