Webhooks
Contents
The platform can provide real-time data about connected devices via HTTP webhooks. This guide covers the types of events that are sent by the platform, as well as how to establish and manage a webhook within the platform.
The platform will send different data for different types of events.
Device Events
The list of all device events sent by the platform is:
deviceEventConfig
deviceEventQueueAction
deviceEventUpdateAction
deviceEventSetState
deviceEventUpdated
deviceEventRemove
deviceEventDeleted
The platform will send a consistent data payload for events, making it easy for webhook consumers to identify the type of event received and handle the content for that specific event. Payloads have a type field indicating which event was sent, as well as a content field containing the data for that event, structured as:
{
type: string;
content: {...}
}
deviceEventConfig events are sent when a device within the platform is configured with a new Trait configuration.
{
type: 'deviceEventConfig';
content: {
deviceId: string;
traits: {
traitName: string;
traitInstance: string;
properties: {...}
}[];
}
}
deviceEventQueueAction events are sent when an action has been queued for a device within the platform.
{
type: 'deviceEventQueueAction';
content: {
deviceId: string;
actionId: string;
traitName: string;
traitInstance: string;
actionName: string;
actionParameters: {...};
}
}
deviceEventUpdateAction events are sent when an action status has been updated for an action made against a device within the platform.
{
type: 'deviceEventUpdateAction';
content: {
deviceId: string;
actionId: string;
status: string;
}
}
deviceEventSetState events are sent when a state is set for device within the platform. These events are correlated with an actionId, if they occured as a result of an action against the device.
{
type: 'deviceEventSetState';
content: {
deviceId: string;
traitName: string;
traitInstance: string;
fieldName: string;
value: unknown;
sampledAt: string;
inResponseToActionId?: string;
}
}
deviceEventUpdated events are sent when a device within the platform is updated with new metadata.
{
type: 'deviceEventUpdated';
content: {
deviceId: string;
}
}
deviceEventRemove events are sent when a device is removed from the platform.
{
type: 'deviceEventRemove';
content: {
deviceId: string;
}
}
deviceEventDeleted events are sent when a device’s metadata is deleted from the platform.
{
type: 'deviceEventDeleted';
content: {
deviceId: string;
}
}
Linked Account Events
The list of all account events sent by the platform is:
linkedAccountAuthorizationEvent
linkedAccountAuthorizationEvent events are sent when an account’s authorization status is changed.
{
type: 'linkedAccountAuthorizationEvent';
content: {
linkedAccountId: string;
authorizationStatus: { AUTHORIZED | NOT_AUTHORIZED}
}
}
Managing a webhook
Currently, administrators of the Yonomi platform are responsible for creating and managing webhooks. Please work with them to create and manage your webhooks.
Filtering on events
To more efficiently receive events from the platform, we recommend limiting/narrowing the types of events that your webhook endpoint receives. A webhook can be configured with any subset of events, and your webhook consumer will only receive events that it is subscribed to.
Event delivery
The platform guarantees at-least-once delivery of events. Your application must be able to handle a single event being delivered more than once.
Handling events
When the platform sends an event to your webhook consumer, you must respond with a status code 200 response within 1.5 seconds, or the platform will treat this as a failed event delivery.
Delivery failures
If the platform realizes that an event failed to deliver, it will attempt to re-deliver the event for up to 5 minutes, with exponential backoff. After this, the event is marked as failed and it is dropped.