Event catalog

Novatrade24 delivers 8 event types. Subscribe to the ones your integration needs. Common subscriptions are compliance.status_changed, kyc.vies_check_failed, and the two self_service_invitation.* events. Every event shares the common envelope described in Webhooks overview. This page documents the event-specific data payload.

`compliance.status_changed`

Order compliance rollup transitioned between INCOMPLETE / VALID / CANCELLED.

{
  "orderUuid": "o1p2q3r4-...",
  "previousStatus": "INCOMPLETE",
  "currentStatus": "VALID",
  "blockers": []
}

An order leaves VALID only through a staff action on the order: reopening a closed order, for instance, moves it back to INCOMPLETE, and blockers[] then lists what the reopened order is waiting for. A failed VIES re-check never moves the status: it fires kyc.vies_check_failed and the buyer module reports viesResult: INVALID, but complianceStatus and blockers[] stay as they were. Refetch GET /orders/{uuid}/compliance for full detail. blockers[] carries the same entries as the rollup: module, a code from ComplianceBlockerCode, an optional documentType, and a message that is prose for a person and must not be parsed. VALID does not mean blockers[] is empty. NT24 staff can force-close an order, so a currentStatus: VALID delivery may still list outstanding items.

`kyc.vies_check_failed`

A VIES check on a buyer’s VAT number failed. Urgent: the buyer module of the rollup reports viesResult: INVALID, but the order’s complianceStatus does not change.

{
  "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. Nothing on the order blocks on this event, so do not wait for a blocker to appear before acting on it. Note that the INVALID above is currentResult, the VIES answer for this VAT number. It is not a complianceStatus: the rollup reports INCOMPLETE, VALID or CANCELLED, and has no failed state.

`kyc.verification_completed`

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

{
  "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.

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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

{
  "url": "https://your-system.example/hooks/novatrade",
  "events": [
    "compliance.status_changed",
    "kyc.vies_check_failed",
    "kyc.verification_completed",
    "self_service_invitation.*",
    "webhook.endpoint_auto_paused"
  ]
}

Wildcard * (root) is not supported. See Webhook setup.

Signature verification

Validate every incoming delivery.

Replay and test

Delivery history, manual replay, synthetic test fires.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

`compliance.status_changed`

`kyc.vies_check_failed`

`kyc.verification_completed`

`prospect.submitted`

`self_service_invitation.used`

`self_service_invitation.expired`

`webhook.endpoint_auto_paused` (meta)

`webhook.delivery_failed_terminal` (meta)

Subscribing

Next

Signature verification

Replay and test

​compliance.status_changed

​kyc.vies_check_failed

​kyc.verification_completed

​prospect.submitted

​self_service_invitation.used

​self_service_invitation.expired

​webhook.endpoint_auto_paused (meta)

​webhook.delivery_failed_terminal (meta)

​Subscribing

​Next

Signature verification

Replay and test

`compliance.status_changed`

`kyc.vies_check_failed`

`kyc.verification_completed`

`prospect.submitted`

`self_service_invitation.used`

`self_service_invitation.expired`

`webhook.endpoint_auto_paused` (meta)

`webhook.delivery_failed_terminal` (meta)

Subscribing

Next