Dash

Developers


Dash Chassis API Resources

> Chassis Webhooks

Webhooks

A webhook is a client application defined callback. In DASH, we let applications register a single url and we'll POST events to this url in real-time. When these events are triggered, Dash will call your registered webhook url and deliver a Payload.

Webhook Registration

To register a webhook URL, you need to make the following API request.

POST https://7w4xh45731.execute-api.us-east-1.amazonaws.com/prod/authclient/webhooks/register

The POST message body should contain the following parameters in JSON format:

Example request:


                    {
                    "authClientId": "GJK88NjZWQtOWNkZC00ZDg1LWIzOTEtN2ViYmMyM2EyYjQz",
                    "secret": "6767FYGFHF567NMBJGHFHGVGHFGHnmhgUKH",
                    "webHookUrl":"http://myapp.com/webhooks",
                    "eventTypes":["ignition_on","check_engine_light_alert"]
                    } 

When an event that you registered for is triggered within Dash, your webhook url will be invoked with a payload containing information about the event. Each payload delivered will contain a userId property containing the id of the user, a payload property containing the actual payload and an eventType property identifying the type of the event that occurred.

Security considerations

In order to ensure that the webhook was invoked by Dash and not by an untrusted source, we attach a security header called X-Dash-Signature to the http request. The security header is created in the following steps:

  1. The POST body is encrypted (HMAC SHA1) using the client secret.
  2. To ensure that the resulting value is only ASCII, the encrypted value is then Bas64 encoded.

If you want to verify the authenticity of the request, you can re-assemble the security header string by going through the exact same process.

The following are the event types along with the payload that gets delivered when they are triggered within Dash.


Webhook

Payload

Description

Example webhook payload:


                 {
                 "userId": "GJK88NjZWQtOWNkZC00ZDg1LWIzOTEtN2ViYmMyM2EyYjQz",
                 "eventType": "bumpersticker_earned",
                 "payload": {
                    dateEarned: "2014-08-28T20:45Z",
                    vehicleId: "7061f4c3-b77c-45c6-a054-3c211f9e1a3b",
                    title: "End Of Summer Road Trip",
                    description: "Let's ride off into the sunset for one last summer road trip! Here's to amazing memories and more to come.",
                    bumperStickerImageUrl: "https://xb2a5xb6ne.execute-api.us-east-1.amazonaws.com/prod/s/koE_VwRfWaLMChHL0yieIA"
                    }
                 } 

Webhook Update

To update a previously registered webhook URL, you need to make the following API request (the body data is the same as the registration endpoint, defined above).

PUT https://7w4xh45731.execute-api.us-east-1.amazonaws.com/prod/authclient/webhooks/update