- Homepage
- Webhooks
Webhooks
The Moonsense Cloud offers to main ways two 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/jsoncontent type will deliver the JSON payload directly as the body of thePOSTrequest.application/x-www-form-urlencodedcontent type will send the JSON payload as a form parameter calledpayload.
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
| Header | Description |
|---|---|
project_id | Project Id for which the app sending the data belongs to. |
app_id | App Id for which the app sending the data belongs to. |
session_id | Session Id for which the data belongs to. |
journey_id | Journey Id that is attached to the session. |
session_labels | List 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:
| Header | Description |
|---|---|
X-Moonsense-Delivery | A GUID to identify the delivery. |
X-Moonsense-Event | Name 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
}
}