Event catalog

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. This page documents the event-specific data payload.

`compliance.status_changed`

Order compliance rollup transitioned between INCOMPLETE / VALID / INVALID.

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

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

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

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

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

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

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`

`compliance.decision_made`

`kyc.vies_check_failed`

`kyc.verification_completed`

`export_file.generated`

`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

​compliance.decision_made

​kyc.vies_check_failed

​kyc.verification_completed

​export_file.generated

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

`compliance.decision_made`

`kyc.vies_check_failed`

`kyc.verification_completed`

`export_file.generated`

`prospect.submitted`

`self_service_invitation.used`

`self_service_invitation.expired`

`webhook.endpoint_auto_paused` (meta)

`webhook.delivery_failed_terminal` (meta)

Subscribing

Next