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.

​
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 — 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.