# Subscription model

This page explains how webhook subscriptions are structured, how you can control which events to receive, and how delivery to your endpoints works.

Each subscription is created with the [Create Webhook Subscription](/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription) API.
A subscription is owned by a `subscriberId` (the company that manages it), delivers to a single HTTPS `url`, lists the `eventTypes` you want to receive, and optionally narrows the source companies whose events you receive through an `eventSource` object. When `eventSource` is omitted, it defaults to the subscriber's own company (`COMPANY = subscriberId`).

A sample create subscription request looks like this:


```json POST /v3/webhooks/subscriptions
{
  "subscriberId": "company1-id",
  "name": "spotnana_us",
  "url": "https://partner.com/api/webhooks/pnr",
  "eventTypes": ["PNR_V3"],
  "eventSource": {
    "scopes": [
      { "predicates": [ { "type": "COMPANY", "comparator": "IN", "values": ["company1-id"] } ] }
    ]
  },
  "customHeaders": { "X-Custom-Header": "my-value" }
}
```

The response returns the subscription `id` and an `hmacSigningSecret` that is shown only once.
Store this `hmacSigningSecret` securely (see [Authentication](/docs/webhooks/webhook-auth#hmac-signature-verification) for more information).

## Supported subscription models

Spotnana supports two ways to configure webhook subscriptions depending on how your system is set up.

### Option A: Single TMC-level webhook (recommended)

One webhook subscription that covers all of your customers.
Spotnana delivers all events across all organizations to a single endpoint,
and you route them internally based on the organization identifier (i.e., an `organizationId`) included in every payload.


```mermaid
flowchart LR
   S[Spotnana] --> E[Single TMC partner's
   endpoint]
   E --> R{Route by organization ID}
   R --> O1[Org A]
   R --> O2[Org B]
   R --> O3[Org C]
```

This is the **recommended** model for partners integrating across multiple customers as it
reduces the overhead of managing multiple subscriptions.

For this model, set `subscriberId` to your TMC and scope the subscription to every company that TMC manages with a `CONTRACTING_TMC` predicate. Companies you onboard later are covered automatically, with no subscription changes:


```json POST /v3/webhooks/subscriptions
"eventSource": {
  "scopes": [
    {
      "predicates": [
        {
          "type": "CONTRACTING_TMC",
          "comparator": "IN",
          "values": [
            "your-tmc-id"
          ]
        }
      ]
    }
  ]
}
```

To scope a single TMC-level subscription to a **specific subset** of the companies you manage (rather than all of them), use a `COMPANY` predicate that lists those company IDs.
The `values` are matched with `IN` logic, so the subscription receives events from any company in the list:


```json POST /v3/webhooks/subscriptions
"eventSource": {
  "scopes": [
    {
      "predicates": [
        {
          "type": "COMPANY",
          "comparator": "IN",
          "values": [
            "company1-id",
            "company2-id",
            "company3-id"
          ]
        }
      ]
    }
  ]
}
```

### Option B: Organization specific webhooks

Each customer organization has its own dedicated webhook subscription with a separate endpoint URL and authentication credentials.
Spotnana delivers events for that organization exclusively to the configured endpoint.


```mermaid
flowchart LR
    S([Spotnana]) --> E1[[Endpoint A]]
    S --> E2[[Endpoint B]]
    S --> E3[[Endpoint C]]
    E1 --> O1[(Org A)]
    E2 --> O2[(Org B)]
    E3 --> O3[(Org C)]
```

This model is a good fit for partners who manage distinct integrations per customer.

For each subscription, set `subscriberId` to the organization it serves.
You can either omit `eventSource` (it defaults to `COMPANY = subscriberId`) or set it explicitly:


```json POST /v3/webhooks/subscriptions
"eventSource": {
  "scopes": [
    { "predicates": [ { "type": "COMPANY", "comparator": "IN", "values": ["company1-id"] } ] }
  ]
}
```

**Note:** While our platform supports this subscription model we do not prefer this approach as it requires separate
setup for each organization. We recommend using option A instead.

## Event and operation filtering

Partners can choose which event and operations that they wish to receive. You can:

- Subscribe to only specific webhook events through the `eventTypes` field (e.g., [PNR_V3](/docs/openapi/webhookeventapi/webhooks/paths/pnr_v3/post)).
- Control which company's events a subscription receives through the optional `eventSource` object. If the `eventSource` is omitted, the subscription defaults to the subscriber's `companyId`.
- Route a delivered event to the right customer within a single TMC-level subscription using the `audience` > `organizationId` field included in every payload.


**Note:** Currently the operation filtering is implemented as a blacklist (i.e., to exclude specific operations that you don't want to receive).

## Event delivery

Here are some important points to note regarding webhook delivery:

- Webhooks support payload delivery to one endpoint per subscription.
- You can create multiple subscriptions (each delivering to its own endpoint) using the [Create Webhook Subscription API](/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription).