Subscription model

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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 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:

{
  "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 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.

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:

"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:

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

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:

"eventSource": {
  "scopes": [
    { "predicates": [ { "type": "COMPANY", "comparator": "IN", "values": ["company1-id"] } ] }
  ]
}

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).
• 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.