Webhook Subscription

APIs to create, list, retrieve, and update webhook subscriptions.

Operations

Create Webhook Subscription

Request

Security

Bearer

Bodyapplication/jsonrequired

subscriberIdstring(uuid)required

UUID of the company that owns this webhook subscription.

eventSourceobjectrequired

Defines which event sources a subscription should match. Contains a list of scopes that are OR'd together — an event matches if it satisfies ANY scope.

eventSource.scopesArray of objects(EventSourceScope)non-emptyrequired

List of scopes evaluated with OR logic. An event matches if at least one scope is satisfied.

eventSource.scopes[].predicatesArray of objects(EventSourcePredicate)non-emptyrequired

List of predicates that must all be satisfied for this scope to match.

eventSource.scopes[].predicates[].typestring(EventSourceScopeType)required

The type of event source entity.

Enum"COMPANY""BOOKING_TMC""CONTRACTING_TMC"

eventSource.scopes[].predicates[].valuesArray of strings(uuid)non-emptyrequired

List of entity IDs to match against.

eventSource.scopes[].predicates[].comparatorstring

Comparator for evaluation. Defaults to IN.

Default "IN"

Value"IN"

namestringrequired

Human-readable display name for the subscription. Must be non-blank.

eventTypesArray of strings(WebhookEventTypeEnum)non-emptyrequired

List of event types this subscription should receive. At least one is required.

Items Enum"TRAVELER_V2""PNR_V3""TRIP_DETAILS_V3""PNR_APPROVAL""AGENT_TASK_DETAILS""SERVICE_CHARGE"

urlstring(uri)required

HTTPS endpoint that Spotnana will POST event payloads to. Must use the https scheme and accept POST requests.

isActiveboolean

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.

Default true

customHeadersobject

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

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/webhooks/subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriberId": "96d0a1b8-7f77-4d5c-847e-2afd90ed23b3",
    "eventSource": {
      "scopes": [
        {
          "predicates": [
            {
              "type": "COMPANY",
              "values": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              ],
              "comparator": "IN"
            }
          ]
        }
      ]
    },
    "name": "string",
    "eventTypes": [
      "TRAVELER_V2"
    ],
    "url": "http://example.com",
    "isActive": true,
    "customHeaders": {
      "X-Custom-Header": "my-value",
      "Authorization-Extra": "token123"
    }
  }'

Responses

Successful Webhook Subscription Response

Bodyapplication/json

idstring(uuid)required

UUID of the newly created webhook subscription.

hmacSigningSecretstring

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.

createdAtobject(Date)required

Timestamp at which the subscription was created.

createdAt.iso8601string^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01...required

Example: "2017-07-21"

Response

application/json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "hmacSigningSecret": "string",
  "createdAt": {
    "iso8601": "2017-07-21"
  }
}

List Webhook Subscriptions

Request

Security

Bearer

Path

subscriberIdstring(uuid)required

Query

limitinteger

Default 50

offsetinteger

Default 0

curl -i -X GET \
  'https://api-ext-sboxmeta.partners.spotnana.com/v3/webhooks/subscriptions/subscriber/{subscriberId}/list?limit=50&offset=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful List Webhook Subscriptions Response

Bodyapplication/json

subscriptionsArray of objects(WebhookSubscription)required

Page of webhook subscriptions matching the request.

subscriptions[].idstring(uuid)required

UUID of the webhook subscription.

subscriptions[].namestringrequired

Human-readable display name for the subscription.

subscriptions[].eventTypesArray of strings(WebhookEventTypeEnum)required

List of event types this subscription is configured to receive.

Items Enum"TRAVELER_V2""PNR_V3""TRIP_DETAILS_V3""PNR_APPROVAL""AGENT_TASK_DETAILS""SERVICE_CHARGE"

subscriptions[].subscriberIdstring(uuid)required

UUID of the company that owns this webhook subscription.

subscriptions[].eventSourceobjectrequired

Defines which event sources a subscription should match. Contains a list of scopes that are OR'd together — an event matches if it satisfies ANY scope.

subscriptions[].eventSource.scopesArray of objects(EventSourceScope)non-emptyrequired

List of scopes evaluated with OR logic. An event matches if at least one scope is satisfied.

subscriptions[].eventSource.scopes[].predicatesArray of objects(EventSourcePredicate)non-emptyrequired

List of predicates that must all be satisfied for this scope to match.

subscriptions[].eventSource.scopes[].predicates[].typestring(EventSourceScopeType)required

The type of event source entity.

Enum"COMPANY""BOOKING_TMC""CONTRACTING_TMC"

subscriptions[].eventSource.scopes[].predicates[].valuesArray of strings(uuid)non-emptyrequired

List of entity IDs to match against.

subscriptions[].eventSource.scopes[].predicates[].comparatorstring

Comparator for evaluation. Defaults to IN.

Default "IN"

Value"IN"

subscriptions[].eventSource.scopes[].predicates[].valuesWithLabelArray of objects(EventSourceValueWithLabel)read-only

Server-resolved labels for each entry in values. Read-only, returned only in responses.

subscriptions[].urlstring(uri)required

HTTPS endpoint that Spotnana POSTs event payloads to.

subscriptions[].customHeadersobject

Additional HTTP headers included on every webhook request sent to url. Reserved headers managed by Spotnana (such as Authorization and Content-Type) take precedence over values configured here.

Example: {"X-Custom-Header":"my-value","Authorization-Extra":"token123"}

subscriptions[].isActivebooleanrequired

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.

subscriptions[].createdBystring(uuid)

UUID of the user who created the subscription.

subscriptions[].updatedBystring(uuid)

UUID of the user who last updated the subscription.

subscriptions[].createdAtobject(Date)

Timestamp at which the subscription was created.

subscriptions[].updatedAtobject(Date)

Timestamp at which the subscription was last updated.

totalCountintegerrequired

Total number of subscriptions for the subscriber, across all pages.

Response

application/json

{
  "subscriptions": [
    { … }
  ],
  "totalCount": 0
}

Get Webhook Subscription

Request

Security

Bearer

Path

subscriptionIdstring(uuid)required

curl -i -X GET \
  'https://api-ext-sboxmeta.partners.spotnana.com/v3/webhooks/subscriptions/{subscriptionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Get Webhook Subscription Response

Bodyapplication/json

idstring(uuid)required

UUID of the webhook subscription.

namestringrequired

Human-readable display name for the subscription.

eventTypesArray of strings(WebhookEventTypeEnum)required

List of event types this subscription is configured to receive.

Items Enum"TRAVELER_V2""PNR_V3""TRIP_DETAILS_V3""PNR_APPROVAL""AGENT_TASK_DETAILS""SERVICE_CHARGE"

subscriberIdstring(uuid)required

UUID of the company that owns this webhook subscription.

eventSourceobjectrequired

Defines which event sources a subscription should match. Contains a list of scopes that are OR'd together — an event matches if it satisfies ANY scope.

eventSource.scopesArray of objects(EventSourceScope)non-emptyrequired

List of scopes evaluated with OR logic. An event matches if at least one scope is satisfied.

eventSource.scopes[].predicatesArray of objects(EventSourcePredicate)non-emptyrequired

List of predicates that must all be satisfied for this scope to match.

eventSource.scopes[].predicates[].typestring(EventSourceScopeType)required

The type of event source entity.

Enum"COMPANY""BOOKING_TMC""CONTRACTING_TMC"

eventSource.scopes[].predicates[].valuesArray of strings(uuid)non-emptyrequired

List of entity IDs to match against.

eventSource.scopes[].predicates[].comparatorstring

Comparator for evaluation. Defaults to IN.

Default "IN"

Value"IN"

eventSource.scopes[].predicates[].valuesWithLabelArray of objects(EventSourceValueWithLabel)read-only

Server-resolved labels for each entry in values. Read-only, returned only in responses.

urlstring(uri)required

HTTPS endpoint that Spotnana POSTs event payloads to.

customHeadersobject

Additional HTTP headers included on every webhook request sent to url. Reserved headers managed by Spotnana (such as Authorization and Content-Type) take precedence over values configured here.

Example: {"X-Custom-Header":"my-value","Authorization-Extra":"token123"}

isActivebooleanrequired

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.

createdBystring(uuid)

UUID of the user who created the subscription.

updatedBystring(uuid)

UUID of the user who last updated the subscription.

createdAtobject(Date)

Timestamp at which the subscription was created.

updatedAtobject(Date)

Timestamp at which the subscription was last updated.

Response

application/json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "eventTypes": [
    "TRAVELER_V2"
  ],
  "subscriberId": "96d0a1b8-7f77-4d5c-847e-2afd90ed23b3",
  "eventSource": {
    "scopes": [ … ]
  },
  "url": "http://example.com",
  "customHeaders": {
    "X-Custom-Header": "my-value",
    "Authorization-Extra": "token123"
  },
  "isActive": true,
  "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
  "updatedBy": "b0efe45f-0520-4e21-90f0-7e35f137732e",
  "createdAt": {
    "iso8601": "2017-07-21"
  },
  "updatedAt": {
    "iso8601": "2017-07-21"
  }
}

Update Webhook Subscription

Request

Security

Bearer

Path

subscriptionIdstring(uuid)required

Bodyapplication/jsonrequired

eventSourceobject

Defines which event sources a subscription should match. Contains a list of scopes that are OR'd together — an event matches if it satisfies ANY scope.

namestring

Human-readable display name for the subscription.

eventTypesArray of strings(WebhookEventTypeEnum)non-empty

Replacement list of event types this subscription should receive. If provided, must contain at least one entry; the new list fully replaces the existing one.

Items Enum"TRAVELER_V2""PNR_V3""TRIP_DETAILS_V3""PNR_APPROVAL""AGENT_TASK_DETAILS""SERVICE_CHARGE"

isActiveboolean

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.

urlstring(uri)

HTTPS endpoint that Spotnana will POST event payloads to. Must use the https scheme and accept POST requests.

customHeadersobject

Replacement set of additional HTTP headers to include on every webhook request. Sending an empty map clears all existing custom headers; omitting the field leaves them unchanged. Reserved headers managed by Spotnana (such as Authorization and Content-Type) will override any values supplied here.

curl -i -X PATCH \
  'https://api-ext-sboxmeta.partners.spotnana.com/v3/webhooks/subscriptions/{subscriptionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventSource": {
      "scopes": [
        {
          "predicates": [
            {
              "type": "COMPANY",
              "values": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              ],
              "comparator": "IN"
            }
          ]
        }
      ]
    },
    "name": "string",
    "eventTypes": [
      "TRAVELER_V2"
    ],
    "isActive": true,
    "url": "http://example.com",
    "customHeaders": {
      "headerName1": {
        "X-Custom-Header": "my-value",
        "Authorization-Extra": "token123"
      },
      "headerName2": {
        "X-Custom-Header": "my-value",
        "Authorization-Extra": "token123"
      }
    }
  }'

Responses

Webhook Subscription Updated Successfully

Response

No content

Webhook Subscription API (v3)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code