Signed webhooks

Webhooks are by default sent by our servers over HTTPS. If you want additional security and be able to verify that webhooks indeed are sent by us, we can sign the webhooks with a secret. This is available only on selected plans.

👍

Webhook Secret Key

In our admin panel, navigate to API Settings > Keys and look for the last card on the page. The secret shown there is the key you'll use to calculate the HMAC hash.

How it works

The JSON payload of webhook is the same as it is now, unencrypted and unhashed, no difference.

The only difference is that we'll add a header to the request,
​x-timekit-signature, that contains a string with a HMAC sha256 hash of the JSON payload (stringified) and our shared secret.

You would verify the signature with something like this:

const crypto = require('crypto');

const secret = 'our-shared-secret';
const payload = 'the JSON payload from our request'
const header = 'the x-timekit-signature value from our request'

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (hash === header) {
  console.log('boom, request is verified!')
}
//Please note you need the raw payload as sometimes parsers can introduce
//slight differences in the payload.

<?php

$payload = json_decode('{"the JSON payload from our request"}}');

$secret  = 'our-shared-secret';
$header  = 'the x-timekit-signature value from our request';

$sha = hash_hmac('sha256', json_encode($payload), $secret);

if ($sha === $header) {
    echo 'boom, request is verified!';
}