Skip to main content

Deliver Travel Alerts and Advisories

One of Sitata's core services is the delivery of event risk intelligence notifications about various types of travel disruptions, vetted by our team of risk analysts. A few conditions must be true for a notification to be delivered to a traveller by Sitata:

  1. A user record is present.
  2. The user has an active Subscription with Sitata, or your organization holds the Managed Alerts package (which entitles all of your travellers to alerts without a per-user subscription).
  3. Sitata can determine the user's active location.
  4. The user's active location is affected by the Alert or Advisory published.
  5. An Alert Filter is not blocking the notification.

If the above conditions are met, Sitata will issue a notification for the User and deliver it across various channels such as email, SMS text message, messaging service integrations, and push notification.

info

The conditions above describe notifications that Sitata delivers directly to a traveller. If your organization uses Sitata's whitelabel integration — the Whitelabel Travellers package (Sitata suppresses direct traveller comms and relays them to you) together with Managed Alerts (so your travellers are entitled to alerts without individual subscriptions) — delivery works differently: your users do not need an active Subscription, and you are responsible for relaying notifications yourself (see below). In particular, anonymous travellers are always monitored and always generate notifications, but Sitata never delivers alerts, email, or SMS to them directly — their notifications are relayed to your platform via webhook instead.

How To Control Your Own Delivery

If your organization has the Whitelabel Travellers package configuration with Sitata, then you will be responsible for delivery of the notifications. This configuration is common for clients that are integrating Sitata's service into their own apps and platforms. This setup is also advantageous because it won't be necessary for your organization to disclose any customer data to Sitata - all records can be anonymous. Further, with the Managed Alerts package your users will not need to have an active Sitata subscription to benefit from the risk intelligence notifications.

warning

Note that your organization will need the Whitelabel Travellers package to relay notifications, plus the Managed Alerts package if you want your travellers to receive alerts without individual subscriptions. (These are separate from Advanced Intelligence, which grants the full raw alert feed — see below.)

Integration Overview

At a high level, relaying Sitata's alerts through your own platform is a three-step process:

  1. Register your travellers and their trips. Create a trip for each traveller and — highly recommended — stamp it with your own external_id so you can recognise it later. Optionally, also set an external_id on each traveller associated with the trip. These identifiers are what let you match an incoming alert back to your own records without ever storing Sitata's ids.

  2. Create a webhook for Notification Type 110 (see below). This is how Sitata pushes affected-traveller events to your servers.

  3. Receive and relay alerts. When an event affects one of your travellers, Sitata calls your webhook with the alert plus the affected external_ids and trip_external_ids. Look those up in your database and deliver the alert to your users however you choose — email, SMS, push, in-app, and so on.

The rest of this guide walks through the webhook step in detail.

Create a Webhook

In order to receive information about events and affected users, you will first need to create a Webhook Endpoint on the Sitata platform. This webhook will allow us to send the data to your servers. To create the necessary webhook, you should issue a POST request and register for the Notification Type 110.

Therefore, your POST body to create the webhook should resemble something like the following:

{
    "webhook_endpoint": {
        "enabled_events": [110],
        "enabled": true,
        "url": "https://www.your-company.co/webhooks/sitata"
    }
}

With the webhook in place, Sitata will send information to your platform whenever we publish an event that might affect your users. The body of the Webhook Event will resemble the following:

{
    "attempt_count": 3,
    "company_id": "<YOUR COMPANY ID>",
    "completed": true,
    "created_at": "2020-05-22T03:07:22.898291Z",
    "id": "79cd6f10-1229-4794-9645-ecebbd262417",
    "last_response": {},
    "last_response_status": 200,
    "next_attempt_at": "2020-05-22T03:09:22.875502Z",
    "payload": {
        "event": 110,
        "user_ids": ["79cd6f10-1229-4794-9645-ecebbd262417", "38dslf10-1229-4794-9645-ecebbd323317"],
        "external_ids": ["23039", "10393"],
        "checkin_ids": [],
        "trip_ids": ["2039d6f10-2039-4794-9645-ecebbd262417", "4029310-2039-4794-8273-edc29dd268302"],
        "trip_external_ids": ["2332", "30293830"],
        "alert": {
            // FULL alert body here
        }
    },
    "updated_at": "2020-05-22T03:07:54.267388Z",
    "webhook_endpoint_id": "https://www.your-company.co/webhooks/sitata"
}

Note that all of the alert attributes will be available and multi-lingual fields will have a map of all supported languages.

tip

Webhook event types use the same values as Sitata's Notification Types, but not all notification types are supported for webhooks. The list of supported events can be viewed here.

With the webhook in place, your organization will be in full control of the delivery of the information to the affected users. It will be up to you to chose whether or not to send the information (we strongly advise that you do) and how you wish to send it (e.g. by email or text message or push notification, etc).

Anonymous Travellers

Whitelabel partners can register travellers as anonymous — a privacy-preserving record keyed only by your own external_id, with no traveller PII disclosed to Sitata. Anonymous travellers behave exactly like any other traveller for the purposes of monitoring: Sitata tracks their trip, matches it against published Alerts and Advisories, and generates a notification whenever they are affected.

The difference is delivery. Because an anonymous traveller has no real contact details, Sitata never delivers alerts to them directly:

  • Email and SMS are suppressed at the source — even a message explicitly forced to send is not delivered.
  • There is no push channel, since an anonymous record is never attached to a device.

Instead, every notification for an affected anonymous traveller is relayed to you through the same Notification Type 110 webhook described above. The webhook payload includes the traveller's external_ids (and trip_external_ids), so you can match the alert back to the customer in your own database and deliver it however you choose. In other words, anonymous travellers are fully protected by Sitata's monitoring while your platform remains the sole point of contact with the end user.

Now might be a good time to review the details of Sitata's webhook system or proceed to understand how Sitata's platform can be used completely anonymously so that your organization does not need to disclose customer data to Sitata.