Skip to main content
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:
HeaderExamplePurpose
Content-Typeapplication/jsonFixed
X-Novatrade-Signaturet=1729684200,v1=7a9c5d4e...HMAC-SHA256 signature
X-Novatrade-Event-Idevt_a1b2c3d4e5f6Unique event id
X-Novatrade-Event-Typecompliance.status_changedEvent type for routing
X-Novatrade-Schema-Version1Payload 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)"

​
Next

Signature verification

Validate X-Novatrade-Signature before trusting the payload.

Event catalog

All 10 event types with payload schemas.