Skip to content
/
Integration steps
Last updated

Integration steps

This page explains the end-to-end process of setting up a webhook integration with Spotnana, from initial setup to production deployment.

Step 1: Define your requirements

Before reaching out to Spotnana, identify the following:

  • The webhook event types that are relevant to your use case (for example, PNR_V3 for expense management). See webhook reference to view the list of events we currently support.
  • The operations for which you want the events to be triggered. For each event in the webhook reference, see the operation field and its description to learn more about the different event triggers.
  • Your preferred subscription model.

Step 2: Prepare your endpoint

Set up the HTTPS endpoint that will receive webhook payloads from Spotnana. Your endpoint must:

  • Accept HTTPS POST requests over TLS 1.2 or higher.
  • Respond with HTTP 200 OK upon successful receipt.
  • Implement HMAC-SHA256 signature verification to authenticate incoming webhook payloads.

It is also recommended to implement an asynchronous processing queue so your endpoint can accept events immediately and process them in the background.

Step 3: Create the webhook subscription

Use the Create Webhook Subscription API to create a subscription. To make the API call, you'll need the following information:

RequirementDescriptionExample
A name for the subscription (name)A human-readable identifier for the webhook subscription. It is shown in the Spotnana UI and used for logging purposes. If you don't provide one, Spotnana assigns a default value that you can change later via the update API.spotnana_us, spotnana_inc, or spotnana
Event types (eventTypes)Spotnana uses different webhook event types for the actions occurring on the platform. Review the webhook reference and let us know which events you want to subscribe to.TRAVELER_V2, PNR_V3
Delivery endpoint (url)The HTTPS URL where Spotnana delivers the webhook payloads. Must use the https scheme.https://partner.com/api/v1/pnr-update
Event source (eventSource)The source companies whose events this subscription receives, set via the optional eventSource object (COMPANY, BOOKING_TMC, or CONTRACTING_TMC predicates). If omitted, it defaults to the subscriberId (i.e., the companyId of the company who owns the subscription). See subscription models.CONTRACTING_TMC or BOOKING_TMC scope for a TMC-level subscription
Custom headers (customHeaders)Any additional static HTTP headers Spotnana should send with each webhook request, as key-value pairs. Optional. Spotnana-managed headers (such as Authorization and Content-Type) take precedence over supplied values.{ "X-Custom-Header": "my-value" }

Here's a sample create webhook subscription request:

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

During the setup, you'll be creating this subscription in the sandbox environment. See host URLs documentation for the sandbox URL.

Step 4: Sandbox testing flow

Test the webhook delivery in the sandbox environment. To receive the webhook payload, you must implement an endpoint that authenticates and handles incoming POST requests using the HMAC signing secret returned when the subscription was created.

Here's an overview of the webhook delivery flow:

  1. Spotnana sends webhook payloads to your delivery endpoint, signed with the HMAC signing secret returned in the Create Webhook Subscription API response (shown only once, at creation).
  2. A POST request is sent to your authenticated endpoint. This request contains the following information:
    1. Message Generation Timestamp: Helps troubleshoot consistency issues with out-of-order deliveries.
    2. Event Type: Identifies the event that triggered the webhook notification.
    3. Operation: Describes the specific change that triggered the event (e.g., FLIGHT_CANCELLED or BOOKING_CREATED).
    4. Payload: Contains the event data.
    5. Audience: Contains the organizationId needed for a TMC to identify and route the message to the respective organization.
  3. After receiving the webhook message, your API must send a 200 OK response indicating a successful delivery. Any response other than 200 OK will be treated as message delivery failure and will cause the retry mechanism to be initiated.

The sandbox environment mirrors production and uses supplier test environments, so no real bookings or charges are involved.

During this test, make sure your system:

  • Handles the HMAC authentication protocol.
  • Receives the event payload and parses the data correctly.
  • Returns a 200 OK response after the webhook message is successfully received.

Step 5: Deploy to production

Once you've validated that the integration, webhook delivery, and handling are successful through repeated testing in sandbox, you can create the subscription in the production environment. Follow Step 3 by replacing the sandbox URL with the live production URL. See the host URLs documentation to identify the production URL.

Step 6: Monitor and maintain

After going live, ongoing monitoring is important to keep your integration healthy:

  • Track webhook delivery success rates and set up alerts for elevated failure rates.
  • Log all incoming events including trace and span IDs for debugging purposes.
  • Monitor endpoint response times to avoid timeouts.
  • Periodically check the webhook changelog to monitor for any new feature releases.

Spotnana has an active monitoring that tracks the 200 OK response for every webhook event delivery.

Previous page
Next page
Copyright © 2026 Spotnana Technology, Inc.