Set up webhooks
Once you integrate the SDK, HyperTrack auto-magically starts generating intelligent events about your users like stuck in traffic, took a slower route or an unscheduled stop, out of network, out of GPS connectivity, etc. In this guide, we will set-up webhooks to consume these events so as to trigger custom actions like sending a notifications/email to your customer or to send an alert to your Slack channel.
Webhook endpoints are URLs defined by users to which HyperTrack sends events. An event is an account occurrence. Each occurrence has a corresponding Event object. When the event occurs, 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.
Step 1: Setup webhook endpoint
Creating a webhook endpoint on your server is no different from creating any other route or API on your server. The webhook endpoint should not have any authentication. 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.
Step 2: Configure webhook on dashboard
Visit the Settings → Account section of the Dashboard and enter the webhook endpoint that you have setup for HyperTrack.
Step 3: Respond to webhooks
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 of 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.
Here are a few best practices to note as you set up webhooks.
- 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:
- Parse the JSON data as above.
- Grab the received Event object ID value.
- Use the Event object ID in a retrieve event API call.
- Take action using the returned Event object.