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:

deviceEvent-config
deviceEvent-queueAction
deviceEvent-updateAction
deviceEvent-setState
deviceEvent-updated
deviceEvent-remove
deviceEvent-removed

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: {...}
}

deviceEvent-config events are sent when a device within the platform is configured with a new Trait configuration.

{
  type: 'deviceEvent-config';
  content: {
    deviceId: string;
    traits: {
      traitName: string;
      traitInstance: string;
      properties: {...}
    }[];
  }
}

deviceEvent-queueAction events are sent when an action has been queued for a device within the platform.

{
  type: 'deviceEvent-queueAction';
  content: {
    deviceId: string;
    actionId: string;
    traitName: string;
    traitInstance: string;
    actionName: string;
    actionParameters: {...};
  }
}

deviceEvent-updateAction events are sent when an action status has been updated for an action made against a device within the platform.

{
  type: 'deviceEvent-updateAction';
  content: {
    deviceId: string;
    actionId: string;
    status: string;
  }
}

deviceEvent-setState 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: 'deviceEvent-setState';
  content: {
    deviceId: string;
    traitName: string;
    traitInstance: string;
    fieldName: string;
    value: unknown;
    sampledAt: string;
    inResponseToActionId?: string;
  }
}

deviceEvent-updated events are sent when a device within the platform is updated with new metadata.

{
  type: 'deviceEvent-updated';
  content: {
    deviceId: string;
  }
}

deviceEvent-remove events are sent when a device is removed from the platform.

{
  type: 'deviceEvent-remove';
  content: {
    deviceId: string;
  }
}

deviceEvent-deleted events are sent when a device’s metadata is deleted from the platform.

{
  type: 'deviceEvent-deleted';
  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.