Integration guide

To subscribe to Spotnana’s webhooks requires that you contact and collaborate with our engineering team. The following steps explain the process for enabling webhooks and what the shared responsibilities are.

Step 1: Requirement gathering

To integrate with Spotnana webhooks, the initial step will involve gathering requirements. Discuss your specific requirements for webhook integration with the Spotnana engineering team. Provide the following details to get started:

Requirement	Description	Example
A name for the webhook integration	A unique identifier for the webhook subscription, preferably the name of the partner's business entity. Even if you subscribe to more than one webhook, you can still just provide a single name. This unique identifier will be used by Spotnana's internal configuration and for logging purpose.	`spotnana_us`, `spotnana_inc`, or `spotnana`
Event type	Spotnana uses different webhook event types for the actions occurring on the platform. Review the webhook reference document and let us know the events that you wish to subscribe to.	`TRAVELER_V2`, `PNR_V3`
Authentication endpoint	The OAuth endpoint URL that Spotnana should call to generate bearer tokens for authentication.	`partner.com/api/v1/auth`
Delivery endpoint	The delivery endpoint URL where partners would like to receive the webhook payload sent by Spotnana.	`partner.com/api/v1/pnr-update`
Client ID	A unique identifier (recognized by the partner systems) used on the authentication requests sent by Spotnana.	`abcdefgh-ffff-4444-a1b2-123abc456def`
Client secret	A unique secret code (recognized by the partner systems) used on the authentication requests sent by Spotnana.	`lweoincoeEs6inbMEbI4Sl5kjowe_weboMoibwPgoasdrbsewo3r23`
Event filters	You can specify if you wish to receive webhooks for one or more contracting TMCs, booking TMCs, or for the partner organizations. For example, if you wish to receive the `PNR_V3` webhook for two specific organizations, we can configure this filter during the setup. You would then only receive webhook messages for those two organizations.	Filter by specific contracting TMCs, booking TMCs, or by partner organizations.
Other form fields	Any other form fields we should use in the API request header for authentication.	An API version header `API-Version: 2.0` must be used on all API calls.

Step 2: Non-production setup

Spotnana will configure your webhook subscription in our non-production environment based on your requirements. This setup enables end-to-end testing and validation before deploying it to production.

Note: You can use our sample receiver (powered by Node.js) as a reference to create your own endpoint for receiving webhook messages.

Step 3: Handling the webhook delivery

Once the initial setup and integration test is completed, we’ll test the webhook delivery in the non-production environment. To receive the webhook payload, you must implement an endpoint that authenticates and handles incoming POST requests using the credentials provided during setup.

Note: Spotnana webhooks support payload delivery to one endpoint per subscription. This means the same message cannot be delivered to multiple endpoints.

Here’s an overview of the webhook delivery flow:

Spotnana authenticates with your delivery endpoint using the credentials provided. Since the credentials are only used by the specific delivery node, your endpoint must support concurrent authentication requests from multiple systems using the same credentials.
A POST request is sent to your authenticated endpoint. This request contains the following information:
- Message Generation Timestamp: Helps troubleshoot consistency issues with out-of-order deliveries.
- Event Type: Identifies the event that triggered the webhook notification.
- Operation: Describes the specific change that triggered the event (e.g., FLIGHT_CANCELLED or BOOKING_CREATED).
- Payload: Contains the event data.
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 begins the retry mechanism.

Step 4: Deploy to production

Once we’ve validated that the integration, webhook delivery, and handling are successful through repeated testing, we’ll deploy your webhook subscription to production and continue to monitor the live data flow.