Receiving webhooks

Webhook endpoints are URLs defined by users to which HyperTrack sends events. An event is an account occurrence, such as a trip being started, a task being completed, or a task getting delayed, or a driver taking a slower route. Each occurrence has a corresponding Event object.

When the event occurs - for example, when a task status changes, HyperTrack creates an Event object. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. HyperTrack then sends the Event object to the URL in your account's webhooks setting via an HTTP POST request. You can find a full list of all event types in the API docs. You might use a webhook to trigger a notification to your consumer that a delivery may be delayed, or the driver is arriving soon, or send a receipt email when the task has been completed.

Configuring webhooks

Webhooks are configured in the account settings section of the Dashboard. You can enter any URL you'd like to have events sent to. This should be a dedicated endpoint on your server, coded per the instructions below.

Webhook config

Receiving a webhook notification

Creating a webhoook endpoint on your server is no different from creating any other route or API on your server. Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object. Here is an example JSON of the body of the request.

{
  "id":"6d6e827c-93ab-492c-a2c3-5c5fef9312fe",
  "event_type":"task.completed",
  "data":{
    "object":{
      "id":"41caa9f2-ad63-4a8b-98ed-1414c372e1ce",
      "driver_id":"d0ae4912-2074-45ef-a7c0-76be58639ea9",
      "is_live":false,
      "initial_eta":"2016-03-09T07:28:40.601013Z",
      "eta":"2016-03-09T07:28:40.601013Z",
      "start_location":{
        "type":"Point",
        "coordinates":[
          -122.420044,
          37.774543
        ]
      },
      "end_location":{
        "type":"Point",
        "coordinates":[
          -122.402248,
          37.78929
        ]
      },
      "started_at":"2016-03-09T07:13:05.026689Z",
      "ended_at":"2016-03-09T09:06:39.073770Z",
      "distance":0,
      "encoded_polyline":"",
      "tasks":[
        "77b9a3fa-a3ab-4840-aadb-cd33442ca45b"
      ],
      "vehicle_type":"",
      "created_at":"2016-03-09T07:13:05.026316Z",
      "modified_at":"2016-03-09T09:06:39.079374Z"
    }
  },
  "created_at":"2016-03-09T22:39:18.950318Z",
  "modified_at":"2016-03-09T22:39:18.950457Z"
}

The webhook endpoint should not have any authentication. Also, if you're using Rails, Django, or another web framework, your site may automatically check that every POST request contains a CSRF token. If so, you may need to exempt the webhooks route from CSRF protection to receive webhooks.

If you use an HTTPS URL for your webhook endpoint, we will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside the this range, including 3xx codes, will indicate that you did not receive the webhook.

If a webhook is not successfully received for any reason, we will continue trying to send it once every 3 minutes up to a maximum of 3 retries. Webhooks cannot be manually retried after this time, though you can query for the event to reconcile your data with any missed events.

Best practices

If your webhook script performs complex logic, or makes network calls, it's possible the script would timeout before we see its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.

For optimum security, you can confirm the event data with us before acting upon it. To do so:

  1. Parse the JSON data as above.
  2. Grab the received Event object ID value.
  3. Use the Event object ID in a retrieve event API call.
  4. Take action using the returned Event object.

results matching ""

    No results matching ""