Domain Event Service (Webhooks)

Introduction

Our Domain Event Service enables you to receive real time data through using webhooks. Webhooks avoid the need to poll for data and instead a push mechanism is used to provide data as soon as it is available. This means rather than fetching data on a continuous basis or being reliant on bulk methods (such as through the Data Delivery Service), webhooks can be used to create efficiencies and support various use cases.

The below diagram provides a high-level illustration of how webhooks work:

To describe the flow:

1. An "event" is triggered. An event could be your customer completing their trip, updates being made to their scoring etc. Further information about the events available can be found in the "Available Events" section.

2. As part of each "event", a request payload is generated. The payload provides details which are relevant to the event which has occurred. For example, if your customer has just completed a journey, the corresponding event payload will contain details such as; the transport mode used, the distance driven, start/end time etc.

3. The event/request payload which has been generated is then pushed to yourselves (using your webhook URL) in order to consume/ingest the data provided.

As the payload provided as part of the "event" contains a number of attributes, this in many cases avoids subsequent API calls having to be made to enrich the data obtained via the webhook.

Available Events

The below table shows the events which are available to yourselves and can be subscribed to:

Getting Started

Using our webhooks are as easy as 1-2-3:

1. Visit the Automotive Portal, select "WEBHOOK MANAGEMENT" from the menu followed by "New Webhook". From the window displayed, enter your webhook URL and select the event type(s) you wish to receive data for. Note: Multiple events can be selected through using the Ctrl button on your keyboard and clicking on the desired events.

2. Test the webhook(s) through simply using the "Test" function in the Automotive Portal.

3. Observe the events coming into your URL.

Tip: if you do not currently have a webhook URL available but would like to test the events, https://webhook.site/ can be used to provide a mechanism to test in the meantime. If experiencing issues with receiving webhook events, in the first instance please take a look at https://learn.microsoft.com/en-us/azure/event-grid/webhook-event-delivery#endpoint-validation-with-cloudevents-v10.

Integration Flow

The below diagram depicts the key integration touchpoints for our Domain Event Service/webhooks.

##Event payload examples and Data Dictionary

Below are examples of sample request payloads for each of the available events and a dictionary of the attributes exposed:

Driving Event Detected

Payload:

{
  "specversion": "1.0",
  "type": "com.swissre.automotive.detection.drivingevent.detected",
  "source": "tenant-swissre",
  "id": "30fc2ec3-760f-4a3e-87f5-9a3eee0374bb",
  "time": "2022-10-21T11:36:14.1262908Z",
  "data": {
    "id": "swissre:6cb0a3bf-c984-43a4-b7a4-938fa2f54e94:PhoneDistraction:1666351531804:1666351584320",
    "userId": "75fa5939-c1e8-4356-b861-1f9b0573f556",
    "vehicleId": "66670487-d178-4a1f-8f62-08d5f09a9be6",
    "deviceId": "6cb0a3bf-c984-43a4-b7a4-938fa2f54e94",
    "startDateTime": "2022-10-21T11:25:31.804+00:00",
    "endDateTime": "2022-10-21T11:26:24.32+00:00",
    "category": "Distraction",
    "type": "PhoneDistraction",
    "subtype": null,
    "version": "2.0",
    "level": 3,
    "minSpeed": 0,
    "maxSpeed": 9.44444465637207,
    "averageSpeed": 3.0603446960449219,
    "tenantId": "swissre"
  }
}

Dictionary: