Webhooks

The Moonsense Cloud offers to main ways to consume ingested data: through the Python SDK and through webhooks.

Webhooks can be setup to either get notified of new data being available or as different events in the lifecycle of a session. When one of these events get triggered we'll send an HTTP POST payload to the configured webhook URL.

Webhooks can be installed on projects and they will notify you for all sessions across all the applications of a project.

Setting up a webhook

In order to setup a webhook, go to the Connections tab as part of a project and click Add Connection.

Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.

URL

The URL of a webhook is the endpoint that will be hit by a HTTP POST request once an event gets triggered in the Moonsense Cloud. This URL needs to be HTTPS.

Content Type

Webhooks can be encoded and delivered using different content types:

  • application/json content type will deliver the JSON payload directly as the body of the POST request.
  • application/x-www-form-urlencoded content type will send the JSON payload as a form parameter called payload.

Secret

Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from Moonsense. When you set a secret, you'll receive the X-Moonsense-Signature-256 header in the webhook POST request.

The X-Moonsense-Signature-256 header is set by calculating a hash using the SECRET_TOKEN. This signature gets calculated using HMAC hex digest.

Here's an example of computing the signature, using Ruby and Sinatra:

import hashlib import hmac # payload body is the raw payload read from the http request. # signature header is the value of the X-Moonsense-Signature-256 header. def verify_signature(payload_body, signature_header): hexdigest = hmac.new(ENV['SECRET_TOKEN'], msg=payload_body, digestmod=hashlib.sha256).hexdigest() return hmac.compare_digest(hexdigest, signature_header)

Active

By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads by deselecting "Active."

Events

These webhooks fire whenever a certain action happens in the lifecycle of a session.

  • Session Created - ID: 1 - triggers when a new session is created.
  • Bundle Received - ID: 2 - triggers when the Moonsense Cloud receives a bundle (a collection of data points) for a specific session. This event includes the bundle payload.
  • Chunk Persisted - ID: 3 - triggers when the Moonsense Cloud processes the received bundle and persists it, making it available to be read by the Read API (through the Python SDK). This event doesn't include any bundle payload.

Delivery

Webhook payload object common properties

HeaderDescription
project_idProject Id for which the app sending the data belongs to.
app_idApp Id for which the app sending the data belongs to.
session_idSession Id for which the data belongs to.
client_session_group_idClient Session Group Id that is attached to the session.
session_labelsList of sessions that are attached to the session.

Delivery headers

Payloads that are delivered to your webhook's configured URL endpoint will contain a number of special headers:

HeaderDescription
X-Moonsense-DeliveryA GUID to identify the delivery.
X-Moonsense-EventName of the event that triggered the delivery, as string.

Example delivery

{ "project_id": "YsPHHmXUbyGzazfFvhABpf", "app_id": "Wyk48mvsheCX4rg5d954tj", "session_id": "YsPHHmXUbyGzazfFvhABpf", "event_type": 2, "bundle": { "bundle": { "client_time": { "wall_time_millis": 1639623766810, "timer_millis": 6319, "timer_realtime_millis": 6319 }, "pointer_data": [ [...] ], "index": 1, "text_change_data": [ [...] ], "focus_change_data": [ { "determined_at": 6197, "type": 1, "target": { "target_id": "73d501c9-bde6-46aa-9913-a06897c422b1", "target_type": "range" } } ] }, "app_id": "Wyk48mvsheCX4rg5d954tj", "credential_id": "a7RZotQQqYn7wbpei2hAhV", "session_id": "XrwfjYoiUisvBMPLZvD2bh", "server_time_millis": 1639623767326671 } }