Webhook setup

Webhooks deliver state changes to your system in real time. Novatrade24 POSTs a signed JSON payload to your registered URL whenever a subscribed event fires. Ten event types cover the full Phase 1 catalog — see the event catalog.

Register an endpoint

curl -X POST "https://api.novatrade24.com/v1/webhooks" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yoursystem.example.com/hooks/novatrade",
    "events": [
      "compliance.*",
      "kyc.vies_check_failed",
      "kyc.verification_completed",
      "export_file.generated",
      "self_service_invitation.used"
    ]
  }'

Response

{
  "id": "wh_a1b2c3d4",
  "url": "https://api.yoursystem.example.com/hooks/novatrade",
  "events": ["compliance.*", "kyc.vies_check_failed", "kyc.verification_completed", "export_file.generated", "self_service_invitation.used"],
  "partnerIds": null,
  "secret": "whsec_abc123...",
  "status": "ACTIVE",
  "createdAt": "2026-04-22T10:00:00Z",
  "updatedAt": "2026-04-22T10:00:00Z"
}

The secret is returned only in this response. Store it securely on your side — it is not returned by GET or PATCH on the endpoint. If you lose it, rotate by deleting and re-creating the endpoint.

Event subscriptions

Subscribe with specific event types, segment wildcards, or a mix:

Exact — compliance.status_changed
Segment wildcard — compliance.*, kyc.*, self_service_invitation.*
Root wildcard (*) — not supported, for safety

Partner filtering

Optional partnerIds array scopes deliveries to specific authorized partners. Omit (or send null) to receive events for all authorized partners on this endpoint. Useful for marketplace integrators routing events per dealer to different downstream systems.

{
  "url": "https://...",
  "events": ["compliance.*"],
  "partnerIds": ["11111111-2222-3333-4444-555555555555"]
}

Delivery request format

Every delivery is a POST with: Headers:

Header	Example	Purpose
`Content-Type`	`application/json`	Fixed
`X-Novatrade-Signature`	`t=1729684200,v1=7a9c5d4e...`	HMAC-SHA256 signature
`X-Novatrade-Event-Id`	`evt_a1b2c3d4e5f6`	Unique event id
`X-Novatrade-Event-Type`	`compliance.status_changed`	Event type for routing
`X-Novatrade-Schema-Version`	`1`	Payload schema version

Body (envelope + data):

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "compliance.status_changed",
  "schemaVersion": 1,
  "source": "SYSTEM",
  "createdAt": "2026-04-22T10:30:00Z",
  "organizationUuid": "550e8400-...",
  "partnerUuid": "11111111-...",
  "data": {
    "orderUuid": "o1p2q3r4-...",
    "previousStatus": "INCOMPLETE",
    "currentStatus": "VALID",
    "blockers": []
  }
}

Always verify the signature before trusting the payload. See Signature verification.

Idempotent processing

Deliveries are at-least-once. You may receive the same event more than once (retries after network blips, manual replays). Deduplicate on the event id:

// Pseudocode
if (await alreadyProcessed(event.id)) return 200;
await processEvent(event);
await markProcessed(event.id);
return 200;

Always return a 2xx status when you’ve successfully recorded the event, even if your downstream processing hasn’t finished. Process the event asynchronously after acknowledging.

Retry policy

NT24 retries failed deliveries with exponential backoff — up to 10 attempts over 72 hours (1m, 5m, 15m, 1h, 4h, 8h, 16h, 24h, 36h, 48h). After 20 consecutive failures OR 72h of continuous failure, the endpoint is auto-paused. You receive a webhook.endpoint_auto_paused meta-event (delivered to any other active endpoint you have) and an email to your organization admin. Individual events that exhausted retries emit webhook.delivery_failed_terminal. Resume a paused endpoint via PATCH /v1/webhooks/{id} with status: ACTIVE.

Testing without live events

Fire a synthetic test event with any payload:

curl -X POST "https://api.novatrade24.com/v1/webhooks/${WEBHOOK_ID}/test" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "compliance.status_changed",
    "data": {
      "orderUuid": "00000000-0000-0000-0000-000000000000",
      "previousStatus": "INCOMPLETE",
      "currentStatus": "VALID",
      "blockers": []
    }
  }'

The test event is signed identically to real events. Use this to exercise your signature verification and handler logic before live integration.

Delivery history and replay

List the last 30 days of deliveries:

curl "https://api.novatrade24.com/v1/webhooks/${WEBHOOK_ID}/deliveries?status=FAILED" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Manually replay any delivery (successful or failed) within the retention window:

curl -X POST "https://api.novatrade24.com/v1/webhooks/${WEBHOOK_ID}/deliveries/${DELIVERY_ID}/replay" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)"

Signature verification

Validate X-Novatrade-Signature before trusting the payload.

Event catalog

All 10 event types with payload schemas.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Register an endpoint

Response

Event subscriptions

Partner filtering

Delivery request format

Idempotent processing

Retry policy

Testing without live events

Delivery history and replay

Next

Signature verification

Event catalog

​Register an endpoint

​Response

​Event subscriptions

​Partner filtering

​Delivery request format

​Idempotent processing

​Retry policy

​Testing without live events

​Delivery history and replay

​Next

Signature verification

Event catalog

Register an endpoint

Response

Event subscriptions

Partner filtering

Delivery request format

Idempotent processing

Retry policy

Testing without live events

Delivery history and replay

Next