Skip to main content
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 for full payload schemas.
EventWhat it means
compliance.status_changedOrder rollup transitioned (INCOMPLETE → VALID → …).
compliance.decision_madeFinal verdict (VALID_EXPORT or VAT_APPLICABLE).
kyc.vies_check_failedKnown-good buyer became VIES-invalid. Urgent.
kyc.verification_completedMode B iDenfy + AML outcome.
export_file.generatedExport File PDF ready for download.
prospect.submittedNew prospect via public self-service link.
self_service_invitation.usedBuyer completed emailed self-service flow.
self_service_invitation.expiredInvitation TTL elapsed unused.
webhook.endpoint_auto_pausedMeta — your endpoint was paused after failures.
webhook.delivery_failed_terminalMeta — 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 for registration and 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: 
{
  "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 + 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

Setup

Register an endpoint.

Event catalog

Full payload schemas.