Webhook Notifications

Zendrive provides the ability to specify a Webhook where you can receive notifications of interesting events and alerts from Zendrive. The Webhook URL can be specified under Settings > Advanced in your Zendrive Dashboard.

Zendrive SDK includes the following webhooks:

• Collisions Notification

• Trip Scored Notification

Webhook Notification Contents

The Webhook URL must be an HTTPS URL because the notifications contain private information about your fleet. Notifications are sent as a POST request to the Webhook URL with a data block containing a JSON string.

The JSON data contains the following fields:

Field	Description
version	Specifies the version of the notification API being sent. Currently, the value of this field is 3. As the notification API evolves, this field will be incremented.
type	The type of this notification as a string. Your application can use this to handle different types of notifications as needed. New notification types may be added incrementally in the API without a bump in the version.
…	Additional fields present are notification type specific. They are described along with the description of the different notification types.

Webhook Authorization

To prevent unauthorized posting to your endpoints, Zendrive adds an authentication signature header to the Webhook. This signature can be used to validate whether the request originates from Zendrive.

The signature is generated using the HMAC-SHA256 algorithm. Your API Key is the secret, and the notification body is the payload.

Sample Signature

Post /notification_url HTTP/1.1
Host: hostname
Authorization: v1_tud5Hja23wBJrnjXbDr34f0YA5Lug9cq2LR4CFRwrT8=
Content-Length: 949
Accept: */*
Content-Type: application/json
Accept-Encoding: gzip, deflate

How to Validate the Webhook's Authentication Signature

To validate the webhook's authentication signature, perform the following tasks:

1. Fetch the request and extract the request body.

2. Run the body through the HMAC_SHA256 algorithm using your API key as the secret.

3. Extract the Authorization header's value beyond the v1_ prefix.

4. Take the value from step 3 and base64 decode it.

5. Compare the value from Step 4 with the value from Step 2. If they match, the signature is validated.

Sample Validation

Java

import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.bouncycastle.util.Arrays;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class sha256hmacvalidator {
    Mac hmac;
    public sha256hmacvalidator(byte[] secret) {
        try {
            hmac = Mac.getInstance("HmacSHA256");
            hmac.init(new SecretKeySpec(secret, "HmacSHA256"));
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (InvalidKeyException e) {
            e.printStackTrace();
        }
    }
    public boolean validate(byte[] signature, byte[] payload) {
        byte[] calculatedSignature = new byte[this.hmac.getMacLength()];
        calculatedSignature = this.hmac.doFinal(payload);
        return Arrays.constantTimeAreEqual(signature, calculatedSignature);
    }
    
    public static void main(String[] args) {
        String payload = "body_read_from_http_request_in_webhook_notification";
        String based64Signature = "signature_value_read_from_the_header";
        sha256hmacvalidator mySHA256HmacValidator = new
                sha256hmacvalidator("API_Key_of_the_client".getBytes(StandardCharsets.UTF_8));
        boolean validation = mySHA256HmacValidator.
            validate(Base64.getDecoder().decode(based64Signature.getBytes(StandardCharsets.UTF_8)),
                    payload.getBytes(StandardCharsets.UTF_8));
        //System.out.printf("\nValidation is %s", validation);
    }

Python

import hashlib, hmac
import base64

SHA256 = hashlib.sha256

class HmacValidator(object):
    def __init__(self, keybytes, alg=SHA256):
        self.hmac = hmac.new(keybytes, None , alg)

    def validateSignature(self, signatureBytes, payloadBytes):
        self.hmac.update(payloadBytes)
        calculated = self.hmac.digest()
        return hmac.compare_digest(calculated, signatureBytes)

if __name__ == '__main__':
    validator = HmacValidator(keybytes = "Client's_API_Key".encode('utf-8'))
    result = validator.validateSignature(base64.b64decode("signature_value_read_from_the_header"), \
            "body_read_from_http_request_in_webhook_notification".encode('utf-8')
            )
    print("Validation is", result)

C#

using System;
using System.Security.Cryptography;
using System.Text;
using System.Linq;

namespace hmacValidator
{
    class hmacValidator
    {
        HMAC hMAC;
        public hmacValidator(byte[] keybytes) {
            this.hMAC = new HMACSHA256(keybytes);
        }

        public bool validate(byte[] signature, byte[] payload) {
            byte[] calculatedSignature = new byte[this.hMAC.HashSize];
            calculatedSignature = this.hMAC.ComputeHash(payload);
            return calculatedSignature.SequenceEqual(signature);
        }
        static void Main(string[] args)
        {
            String payload = "body_read_from_http_request_in_webhook_notification";
            String based64Signature = "signature_value_read_from_the_header";
            hmacValidator mySHA256HmacValidator = new hmacValidator(Encoding.UTF8.GetBytes("Client's_API_Key"));
            bool result = mySHA256HmacValidator.validate(Convert.FromBase64String(based64Signature),
                    Encoding.UTF8.GetBytes(payload));
            Console.WriteLine("Validation is {0}", result);
        }
    }
}

Webhook Notification Retries

Zendrive will retry notifications to the Webhook in case of all HTTP Errors, Connection Timeouts, SSL Errors, and TooManyRedirectErrors.

The retry mechanism follows a structured schedule, where each attempt is associated with a specific delay period if the retry number is less than or equal to 8. The incremental delay ranges from 30 minutes, doubling with each subsequent attempt to 64 hours for the eighth attempt.

The following table shows the schedule:

Retry Attempt	Delay
1	30 minutes from the initial failure.
2	60 minutes (2*30) from the first retry attempt.
3	2 hours from the second retry attempt.
4	4 hours from the third retry attempt.
5	8 hours from the fourth retry attempt.
6	16 hours from the fifth retry attempt.
7	32 hours from the sixth retry attempt.
8	64 hours from the seventh retry attempt.

It is possible that your Webhook receives duplicates of the same notification from Zendrive. Your Webhook handler must handle the duplicates, as required.