Secure Webhooks

eDRV Webhook Signatures

eDRV can optionally sign webhook events it sends to your endpoints by including a signature in each event’s edrv-signature header. This allows you to verify that the events were sent by eDRV, not by a third party. See the code sample below on how you can verify eDRV signatures.

Webhook Endpoint Secret

Before you can verify signatures, you need to retrieve your endpoint’s secret from your Dashboard’s Webhooks settings. Select an endpoint that you want to obtain the secret for, then click the Click to reveal button. An endpoint may subscribe to multiple eDRV Webhook Events.

eDRV generates a unique secret key for each endpoint. If you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on. After this setup, eDRV starts to sign each webhook it sends to the endpoint.

Verifying Signatures

We sign all webhooks with a SHA256 signature and include the signature in the request's edrv-signature header, preceded with sha256=. You don't have to validate the signature, but you should and we strongly recommend that you do.

To validate the payload:

Generate a SHA256 signature using the payload and your endpoint secret. Compare your signature to the signature in the edrv-signature header (everything after sha256=). If the signatures match, the payload is genuine.

📘

Escaped Unicode

Please note that we generate the signature using an escaped unicode version of the payload, with lowercase hex digits. If you just calculate against the decoded bytes, you will end up with a different signature. For example, the string ëä should be escaped to \u00EB\u00E4.

// Verify that the request came from eDRV.
function verifySignature(req, res, buf) {
  var signature = req.headers["edrv-signature"];

  if (!signature) {
    console.error(`Could not find "eDRV-Signature" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.endpointSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Request signature validation failed");
    }
  }
}

Webhook Delivery Failure

If webhook delivery continues to fail for 1 hour, your account admin will receive a Webhooks Disabled alert via email, and your endpoint will be unsubscribed from webhooks. Once you have fixed the issues you will need to subscribe to the Webhooks again.