# Create Webhook Subscription

Endpoint: POST /v3/webhooks/subscriptions
Version: v3
Security: Bearer

## Request fields (application/json):

  - `subscriberId` (string, required)
    UUID of the company that owns this webhook subscription.

  - `eventSource` (object, required)
    Defines which event sources this subscription should match. Replaces the previous
single eventSourceId field with scoped, typed matching.

  - `eventSource.scopes` (array, required)
    List of scopes evaluated with OR logic. An event matches if at least one scope
is satisfied.

  - `eventSource.scopes.predicates` (array, required)
    List of predicates that must all be satisfied for this scope to match.

  - `eventSource.scopes.predicates.type` (string, required)
    The type of event source entity.
    Enum: "COMPANY", "BOOKING_TMC", "CONTRACTING_TMC"

  - `eventSource.scopes.predicates.values` (array, required)
    List of entity IDs to match against.

  - `eventSource.scopes.predicates.comparator` (string)
    Comparator for evaluation. Defaults to IN.
    Enum: "IN"

  - `name` (string, required)
    Human-readable display name for the subscription. Must be non-blank.

  - `eventTypes` (array, required)
    List of event types this subscription should receive. At least one is required.
    Enum: "TRAVELER_V2", "PNR_V3", "TRIP_DETAILS_V3", "PNR_APPROVAL", "AGENT_TASK_DETAILS", "SERVICE_CHARGE"

  - `url` (string, required)
    HTTPS endpoint that Spotnana will POST event payloads to. Must use the https
scheme and accept POST requests.

  - `isActive` (boolean)
    Whether the subscription is active. When false, the subscription is preserved but
incoming events will not be matched against it and no deliveries will be made.

  - `customHeaders` (object)
    Additional HTTP headers to include on every webhook request sent to url. Provided
as a map of header name to header value. Reserved headers managed by Spotnana
(such as Authorization and Content-Type) will override any values supplied here.
    Example: {"X-Custom-Header":"my-value","Authorization-Extra":"token123"}

## Response 201 fields (application/json):

  - `id` (string, required)
    UUID of the newly created webhook subscription.

  - `hmacSigningSecret` (string)
    Secret used to verify the HMAC-SHA256 signature on incoming webhook requests.
Returned only once, at subscription creation, and cannot be retrieved later. Store
it securely.

  - `createdAt` (object, required)
    Timestamp at which the subscription was created.

  - `createdAt.iso8601` (string, required)
    Example: "2017-07-21"

## Response 400 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 401 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 403 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 404 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.