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

# Register a webhook endpoint.



## OpenAPI

````yaml /openapi-integration-v1.yaml post /webhooks
openapi: 3.1.0
info:
  title: Novatrade24 Integration API
  version: 1.0.0-draft
  summary: Customer-facing integration API for the Novatrade24 compliance platform.
  description: >
    The Novatrade24 Integration API lets marketplaces, dealers, and financial

    partners embed EU VAT-compliant cross-border vehicle transactions into

    their own systems.


    The API is organized around the end-to-end compliance workflow:


    1. **Buyer (KYC)** — create or sync a buyer, run VIES, upload KYC documents,
       optionally trigger NT24-led verification.
    2. **Order** — register a VIN-based transaction linked to a buyer.

    3. **Invoice** — submit preliminary and final invoice data and documents.

    4. **Payment** — submit proof-of-payment and trigger pickup readiness.

    5. **Transport** — confirm pickup and delivery with CMR / declarations.

    6. **Compliance rollup** — poll workflow status or subscribe to webhooks.

    7. **Finalization** — download the generated Export File.


    **Status:** Draft — no production endpoint yet. Specification published for

    integration planning. Hosted mock available at
    `https://mock.api.novatrade24.com`.
  termsOfService: https://novatrade24.com/terms
  contact:
    name: Novatrade24 Integration Support
    email: integration-support@novatrade24.com
    url: https://developers.novatrade24.com
  license:
    name: Proprietary
    url: https://novatrade24.com/terms
servers:
  - url: https://api.novatrade24.com/v1
    description: Production (Phase 1 pilot — restricted access)
  - url: https://api.stage.novatrade24.com/v1
    description: Staging environment
  - url: https://mock.api.novatrade24.com
    description: Hosted mock server (Prism) — spec-driven stub responses
security:
  - oauth2ClientCredentials: []
tags:
  - name: Discovery
    description: Organization + capability discovery.
  - name: Buyers
    description: |
      Manage buyer (trade partner) records and KYC lifecycle.
      Buyers are upserted by `(sellerId, vatNumber)`.
  - name: KYC
    description: KYC documents, VIES checks, Mode B verification, profile.
  - name: Self-service invitations
    description: |
      Orchestrate buyer-facing self-service links for KYC submission
      and prospect onboarding.
  - name: Orders
    description: |
      Register vehicle transactions. Orders may contain one or more VINs;
      Phase 1 Santander pilot uses single-VIN orders.
  - name: Invoice
    description: Buyer's VAT-compliance invoice (preliminary or final).
  - name: Payment
    description: Proof-of-payment data and documents; pickup readiness trigger.
  - name: Transport
    description: Pickup + delivery milestones and documents (CMR, declarations).
  - name: Compliance
    description: End-to-end compliance rollup per order.
  - name: Finalization
    description: Final invoice submission and Export File download.
  - name: Prospects
    description: Public prospect submission flow.
  - name: Documents
    description: Typed document download.
  - name: Webhooks
    description: Webhook endpoint registration, delivery history, test-fire.
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Register a webhook endpoint.
      operationId: createWebhook
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
      responses:
        '201':
          description: Registered. Secret is shown once in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        4XX:
          $ref: '#/components/responses/Problem'
        5XX:
          $ref: '#/components/responses/Problem'
components:
  parameters:
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        Client-generated unique key (UUID recommended) for this write operation.
        Identical key + identical body within 24h returns the cached response.
        Identical key + different body returns `422`.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    WebhookCreateRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventSubscription'
        partnerIds:
          type: array
          description: |
            Optional filter — if set, only events for these partners fire on
            this endpoint. Omit for all authorized partners.
          items:
            type: string
            format: uuid
        secret:
          type: string
          description: Optional provided secret. If omitted, server generates.
    WebhookResponse:
      type: object
      required:
        - id
        - url
        - events
        - status
        - createdAt
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventSubscription'
        partnerIds:
          type: array
          items:
            type: string
            format: uuid
        secret:
          type: string
          description: |
            Signing secret — **returned only on the create response**.
            Not included on GET / list.
        status:
          $ref: '#/components/schemas/WebhookStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    WebhookEventSubscription:
      type: string
      description: |
        Event type or segment wildcard (`compliance.*`, `kyc.*`,
        `self_service_invitation.*`). Root `*` is not supported.
    WebhookStatus:
      type: string
      enum:
        - ACTIVE
        - PAUSED
        - DISABLED
    Problem:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        traceId:
          type: string
  responses:
    Problem:
      description: |
        RFC 7807 problem detail. Default fallback for any status not explicitly
        enumerated on the operation. Concrete status is in `status` field.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: |
        OAuth 2.0 client_credentials grant via Keycloak service account.
        Clients are provisioned per `IntegrationOrganization` in the
        `nt24-idp` realm.
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token
          scopes: {}

````