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

# Event catalog

> All 10 Phase 1 webhook events with payload schemas.

Novatrade24 delivers 10 event types in the Phase 1 catalog. Subscribe to
the ones your integration needs — common subscriptions are
`compliance.*`, `kyc.vies_check_failed`, `export_file.generated`, and the
two `self_service_invitation.*` events.

Every event shares the common envelope described in
[Webhooks overview](/concepts/webhooks-overview). This page documents the
event-specific `data` payload.

## `compliance.status_changed`

Order compliance rollup transitioned between `INCOMPLETE` / `VALID` /
`INVALID`.

```json theme={null}
{
  "orderUuid": "o1p2q3r4-...",
  "previousStatus": "INCOMPLETE",
  "currentStatus": "VALID",
  "blockers": []
}
```

On transitions **out of `VALID`** (a VIES re-check failed during transport,
for instance), `blockers[]` lists the now-active blockers. Refetch
`GET /orders/{uuid}/compliance` for full detail.

## `compliance.decision_made`

Final verdict reached. This is terminal — once made, the decision won't
change unless data is corrected and compliance is recomputed.

```json theme={null}
{
  "orderUuid": "o1p2q3r4-...",
  "decision": "VALID_EXPORT"
}
```

`decision` is one of:

* `VALID_EXPORT` — VAT exemption applies.
* `VAT_APPLICABLE` — VAT must be applied on the final invoice.

## `kyc.vies_check_failed`

A VIES check on a buyer's VAT number failed. **Urgent** — blocks active
transactions for that buyer.

```json theme={null}
{
  "buyerUuid": "a1b2c3d4-...",
  "vatNumber": "DE123456789",
  "previousResult": "VALID",
  "currentResult": "INVALID",
  "checkedAt": "2026-04-22T08:00:00Z",
  "reason": "VIES service returned NOT_VALID for the specified VAT number."
}
```

Action: investigate with the buyer immediately. Open orders on this buyer
flip compliance to `INVALID` unless resolved.

## `kyc.verification_completed`

Mode B NT24-led verification finished (iDenfy + AML).

```json theme={null}
{
  "buyerUuid": "a1b2c3d4-...",
  "outcome": "VERIFIED",
  "sessionId": "idenfy_abc123",
  "completedAt": "2026-04-22T09:15:00Z"
}
```

`outcome` is `VERIFIED` or `REJECTED`. For `REJECTED`, `reason` is
populated with a summary from iDenfy / AML.

## `export_file.generated`

Export File PDF ready for download. Fires for every generation (first run
and regenerations).

```json theme={null}
{
  "orderUuid": "o1p2q3r4-...",
  "documentId": "doc_xyz123",
  "version": 2,
  "downloadUrl": "/v1/documents/doc_xyz123/download",
  "generatedAt": "2026-04-25T14:30:00Z",
  "decision": "VALID_EXPORT"
}
```

`downloadUrl` is relative to `https://api.novatrade24.com`. Prefix
accordingly.

## `prospect.submitted`

New prospect submitted via a public self-service link. Customer didn't
trigger this — check `partnerUuid` to route to the right downstream team.

```json theme={null}
{
  "prospectUuid": "p1q2r3s4-...",
  "partnerUuid": "11111111-...",
  "type": "COMPANY",
  "submittedAt": "2026-04-22T11:00:00Z"
}
```

`type` is `COMPANY` or `CONSUMER`.

## `self_service_invitation.used`

Buyer or prospect completed a self-service invitation flow.

```json theme={null}
{
  "invitationUuid": "inv_...",
  "kind": "KYC",
  "buyerUuid": "a1b2c3d4-...",
  "usedAt": "2026-04-22T10:30:00Z"
}
```

* `kind` is `KYC` or `PROSPECT`.
* For `KYC`, `buyerUuid` is populated.
* For `PROSPECT`, `prospectUuid` is populated instead.

Refetch the relevant resource for the submitted data — this event is a
notification, not the data itself.

## `self_service_invitation.expired`

Invitation TTL elapsed without being used. Customer decides whether to
resend.

```json theme={null}
{
  "invitationUuid": "inv_...",
  "kind": "KYC",
  "expiredAt": "2026-05-06T10:10:00Z"
}
```

## `webhook.endpoint_auto_paused` (meta)

Your webhook endpoint was auto-paused due to consecutive failures. Fires
to any **other active endpoint** you have on the same organization.
Separate email also goes to your organization admin.

```json theme={null}
{
  "endpointId": "wh_a1b2c3d4",
  "reason": "CONSECUTIVE_FAILURES",
  "lastSuccessAt": "2026-04-22T08:00:00Z",
  "pausedAt": "2026-04-22T12:45:00Z"
}
```

`reason` is `CONSECUTIVE_FAILURES` (20 in a row) or
`CONTINUOUS_FAILURE_WINDOW` (no success in 72h).

Reactivate with `PATCH /v1/webhooks/{id}` setting `status: ACTIVE` once
the receiving side is fixed.

## `webhook.delivery_failed_terminal` (meta)

An individual event exhausted its retry budget (10 attempts over 72h).
The event is still retrievable from delivery history for manual replay.

```json theme={null}
{
  "endpointId": "wh_a1b2c3d4",
  "eventId": "evt_a1b2c3d4e5f6",
  "eventType": "compliance.status_changed",
  "attempts": 10,
  "lastHttpStatus": 503,
  "lastAttemptAt": "2026-04-25T12:00:00Z"
}
```

Use `GET /v1/webhooks/{id}/deliveries/{deliveryId}/replay` to resend.

## Subscribing

```json theme={null}
{
  "url": "https://your-system.example/hooks/novatrade",
  "events": [
    "compliance.*",
    "kyc.vies_check_failed",
    "kyc.verification_completed",
    "export_file.generated",
    "self_service_invitation.*",
    "webhook.endpoint_auto_paused"
  ]
}
```

Wildcard `*` (root) is not supported. See [Webhook setup](/webhooks/setup).

## Next

<CardGroup cols={2}>
  <Card title="Signature verification" icon="shield-check" href="/webhooks/signature-verification">
    Validate every incoming delivery.
  </Card>

  <Card title="Replay and test" icon="repeat" href="/webhooks/replay-and-test">
    Delivery history, manual replay, synthetic test fires.
  </Card>
</CardGroup>