This section explains how Spotnana delivers webhook events to your endpoint, what to expect when things don't go as planned, and how to design your system to handle issues gracefully.
There are two scenarios where a retry mechanism is invoked:
- When payload creation fails (on the Spotnana system)
- When payload delivery fails (on the partner system)
Spotnana converts the event messages into a webhook payload before delivering them to the partner's endpoint. If there's a failure during this process (e.g., due to network issues), we retry this process every 5 minutes until the payload creation is successful or until the retry limit is exhausted.
Note: The retry limit is configured based on the organization requirements. Speak to your Spotnana account representative to decide on how this value should be set.
If a webhook delivery fails (e.g., due to partner server downtime), Spotnana immediately retries up to 5 times. If all immediate retries fail, the event enters an extended retry phase with exponential backoff over a 2-week period. If delivery still remains unsuccessful, the message is stored for manual intervention.
Note: Only an HTTP 200 OK response is considered a successful delivery. Any other status code including redirects and server errors are treated as a failure and trigger the retry mechanism.
Best practices:
- Make sure your endpoint is configured to always return a 200 OK response when the webhook delivery is successful.
- Monitor your endpoint health continuously and set up alerts for elevated failure rates or latency spikes so you can respond before the retries are exhausted.
Each webhook request has a 40-second timeout, covering the entire request lifecycle including connection setup and waiting for a response. If the partner endpoint does not respond within this window, the attempt is considered failed and enters the retry queue.
Best practice: To avoid timeouts, accept the webhook immediately and process the payload asynchronously in the background.
Spotnana's architecture isolates each partner's subscriptions so that the performance of one partner endpoint does not affect others. However, to avoid out-of-order messages and interleaved transactions due to head-of-line blocking:
- keep API response times low.
- optimize endpoint processing logic.
- use asynchronous processing where possible.
- monitor endpoint performance regularly.
Spotnana does not guarantee that the messages will arrive in order at your endpoint. Network conditions, retry queues, and failure scenarios can all cause events to arrive out of sequence.
Best practices:
- Each event payload includes a
timestampfield indicating when the event was generated. Use this field to determine the correct order when processing events. - Implement a buffering or reordering mechanism on your side to handle out-of-order delivery gracefully using
timestamp.
Due to network conditions or retry scenarios, the same event may occasionally be delivered more than once. To avoid this duplication your webhook processing logic should be idempotent to handle this safely:
Best practices:
- Track processed message IDs to detect duplicates.
- Use the
operationandtimestampfields to identify whether an event has already been processed. - Process the entire payload each time rather than performing diffs, to ensure complete data synchronization.
If your endpoint is unavailable for an extended period and events are lost beyond the retry window, you have the following options to recover missed data:
- Get trip details API: Fetch the current state of any trip using its Trip ID.
- Get PNR API: Fetch individual booking details using a PNR or booking ID.
- Bulk reconciliation: Spotnana can provide a list of Trip IDs and PNR IDs for a given time range, which you can use to pull current state via the APIs listed above.
Tip: Most partners adopt a webhook-primary, API-fallback model rather than using both in parallel at all times.