This page explains the end-to-end process of setting up a webhook integration with Spotnana, from initial setup to production deployment.
Before reaching out to Spotnana, identify the following:
- The webhook event types that are relevant to your use case (for example,
PNR_V3for 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
operationfield and its description to learn more about the different event triggers. - Your preferred subscription model.
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.
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 your 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 purposes. | 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 and let us know which events you want to subscribe to. | TRAVELER_V2, PNR_V3 |
| Operations | Each event has a set of operations that acts as an event trigger. For example, the operation BOOKING_CREATED is triggered when a traveler makes a booking on Spotnana. Review the operation field for each event in the webhook reference and let us know the operations you'd like to set up. | BOOKING_CREATED, BOOKING_TICKETED |
| Delivery endpoints | The delivery endpoint URLs where partners would like to receive the webhook payloads sent by Spotnana. | partner.com/api/v1/pnr-update |
| Event filters | You can specify if you wish to receive webhooks for one or more organizations. | Filter by specific organization IDs. |
| 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. | An API version header API-Version: 2.0 must be used on all API calls. |
We'll 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 credentials provided during setup.
Here's an overview of the webhook delivery flow:
- Spotnana sends webhook payloads to your delivery endpoint, signed with the HMAC signing secret provided during onboarding.
- 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_CANCELLEDorBOOKING_CREATED). - Payload: Contains the event data.
- Audience: Contains the
organizationIdneeded for a TMC to identify and route the message to the respective organization.
- 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.
Note: 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.
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.
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.