Ctrlk
SentianceInsights-Control-TowerImportant Security NoticeLegacy Docs
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Firehose Webhooks

Real-time delivery of events to your backend via Webhooks.

Overview

A common need among Sentiance customers is to react to user activity in real time — whether that's enhancing a travel app based on mode of transport, or surfacing relevant offers when a user plans to visit a store.

Enter the Firehose: Firehose delivers a continuous stream of user activity events to your backend as they are processed on the users device. Delivery is handled through standard Webhooks.

Webhooks

Firehose uses Webhooks to push event data in to your backend. When the Sentiance SDK detects a Transport Event, Driving Events, or Crash Event. it sends an HTTP POST request to your configured endpoint that has the relevant insights for you to imediatly interract with.

Webhook creation and management is done in the Insights Control Tower (ICT) under Developer → Webhooks, and requires the Developer role.

Setup

Follow the steps below to configure and activate your Firehose Webhook.

  1. Create a POST endpoint on your backend secured with Basic Auth or OAuth2. It must return 200 OK on success.

  2. Create a GET endpoint on the same path with the same auth credentials. It must return 200 OK with the JSON body: {"app_id": "<your Sentiance appID>"}

  3. Ensure both endpoints are reachable over HTTPS with an SSL certificate rated grade B or higher. Use ssllabs.com to verify.

  4. In ICT, navigate to Developer → Webhooks and click Create Webhook.

    1. Enter your endpoint URL, select your authorization method, and provide your credentials.

    2. Configure your max payload size, max wait time, and TTL

    3. Click Submit Request. This will start the verification process.

Firehose Webhook requests and changes must be confirmed and approved by Sentiance. Always consult with the Sentiance team when creating or updating.

Once all verifications pass and Sentiance approves the webhook, its status in ICT will update to Verification successful and delivery will begin.

You will be notified of any errors during the verification. Any other status code outside of 200 OK by the POST and GET endpoints will result in an error during the verification process.

Message Delivery

Once active, Sentiance delivers events to your endpoint in a consistent JSON (Envelope)format. The delivery system handles batching, error handling, retention, and security automatically.

Please see below for more details regarding these topics

Batching

To reduce network overhead, messages are batched before delivery both by size and by time. A batch is sent when either threshold is reached first.

Parameter
Default
Configurable Range

Max wait time

5 seconds

1 – 300 seconds

Max payload size

1 MB

23 KB – 4 MB

That is to say that once we have 1 MB worth of data or 5 seconds have passed, we will create a batch of data and send a request. These values can be configured during the Webhook setup

Note: Batching by size is done before gzip compression.

Error handling and Retention

Error Handling

Firehose expects a 200 OK response for every delivered message. Any other response or no response at all is treated as a failure and triggers automatic retries with exponential backoff starting from 100 ms up to 5 minutes.

Sentiance guarantees at-least-once delivery. In rare cases where our server fails to register a successful response, the same message may be delivered more than once. Design your endpoint to handle duplicate events gracefully.

Retention

Each webhook has a configurable Message TTL the maximum time Sentiance will retain and retry undelivered messages. Once a message exceeds its TTL, it is discarded. This ensures that we avoid sending stale information.

For example, if your Message TTL has been set to 30 minutes and your endpoint has been down for 40 minutes, on resuming you will only receive messages that are up to 30 minutes old. Messages from the first 10 minutes of downtime will have been dropped.

Set the TTL when creating your Webhook in ICT based on how much data staleness is acceptable for your use case.

Security

Authentication & Authorization

Sentiance applies multiple layers of security to ensure message integrity and endpoint authenticity. To ensure that your messages originate from Sentiance and not from a malicious third party, we will set a Basic Auth HTTP Authorization header on every request as configured in the Webhook Request

TLS & SSL

All connections must use HTTPS. Sentiance requires a grade B or above SSL certificate. Verify your endpoint at ssllabs.com.

All Firehose requests originate from the following dedicated IPs, Add these to your allowlist if your endpoint enforces IP filtering:

  • 52.213.134.71

  • 34.252.131.81

We perform a list of automated verifications before activating Firehose Webhooks.

Check
Description

SSL Certificate

Valid certificate present on the endpoint

Auth Credentials

Correct Basic Auth credentials accepted

Auth Rejection

Incorrect credentials are rejected (tested explicitly)

App ID

GET endpoint returns the correct Sentiance Application ID To ensure the data gets sent to the correct Application ID

Payload Handling

POST endpoint correctly processes test payloads. These test payloads can be identified by looking for the HTTP header sentiance-payload-type: test

Once automated checks pass, a member of the Sentiance Client team performs a final manual review. You will be notified by email when your Webhook is activated or contacted directly if any issues are found.

Message Reference

All Webhook payloads are delivered in a standardised Envelope format, structured as follows:

  • Envelope A parent object containing a single data child.

  • Data Array The data field is an array of messages either a single message or multiple if batched.

  • Each message contains:

    • data the detected insights details

    • meta message details, including timestamp, message type and app ID

Example of Envelope format

Transports

This message includes the transport id, transport mode, user id, start and end times, app id, detected waypoints and more.

If you need the Driving Insights for motorcycle and car transports, the Transports messages can be enriched with the Driving Events and the Driving scores.

The message examples below gives you the full overview of what data is included

Transport
Transport with Driving Insights

Crash Insights

This type of message includes data regarding a detected crash.

Crash Insights

Smart Geofences

The Smart Geofence message is sent whenever a user enters or exits a preconfigured geofence. One message can contain multiple geofences, if the triggering location touches multiple overlapping geofences.

Smart Geofences

Engagement

These are triggered by engagement actions, like challenges, badges, etc. Can be used to deliver real-time push notifications to users or as general updates from users. They contain the event type and a context map that's custom for each type. All context attributes are of type String.

These messages can only be sent if your application is enabled on the Engagement Platform

Challenge

Trigges when a user completes of fails.

Possible values for challenge state: COMPLETED and FAILED.

Badge

Triggered when a user achieves a badge.

Possible values for badge state: COMPLETED.

Trip

Triggered when a new trip is recorded for a user.

Streak

Triggered when a user breaks a streak.

Possible values for streaks state: BREAK.

Possible values for streak type: STRICT and SELF_COMPETING

Report

Used as trigger for delivering reports to users via email or other channels.

Message

This is a generic category for events that do not fit any of the categories above. For example, an event with type MESSAGE can be triggered for reminders.

Scheduled

Triggered for messages that are scheduled to be delivered at a specific time and date.

Crash Event

Triggered whenever a crash event is detected by our sdk.

Last updated