# 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](/docs/openapi/webhookeventapi/webhooks) 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](/docs/openapi/webhookeventapi/webhooks), see the `operation` field and its description to learn more about the different event triggers.
- Your preferred [subscription model](/docs/webhooks/webhook-config-model#supported-subscription-models).


## 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](/docs/webhooks/webhook-auth#hmac-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](/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription) API to create a subscription.
To make the API call, you'll need the following information:

| Requirement | Description | Example |
|  --- | --- | --- |
| **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](/docs/openapi/webhooksubscriptionapi/webhook-subscription/updatewebhooksubscription) 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](/docs/openapi/webhookeventapi/webhooks) 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](/docs/webhooks/webhook-config-model#supported-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](/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription) request:


```json 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](/docs/spotnana/host_urls_doc) 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](/docs/webhooks/webhook-auth) 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](/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription) 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](/docs/webhooks/webhook-auth#hmac-signature-verification).
- 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](/docs/spotnana/host_urls_doc) 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](/docs/releases/webhookchangelog) to monitor for any new feature releases.


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