> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook setup

> Register an endpoint, subscribe to events, and start receiving signed POSTs on compliance transitions.

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](/webhooks/event-catalog).

## Register an endpoint

```bash theme={null}
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

```json theme={null}
{
  "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"
}
```

<Warning>
  **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.
</Warning>

## 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.

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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](/webhooks/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`:

```typescript theme={null}
// 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Signature verification" icon="shield-check" href="/webhooks/signature-verification">
    Validate `X-Novatrade-Signature` before trusting the payload.
  </Card>

  <Card title="Event catalog" icon="list" href="/webhooks/event-catalog">
    All 10 event types with payload schemas.
  </Card>
</CardGroup>