Verify WebHook Signature

v0 Webhooks

When we send a v0 webhook we add a room-id-hmac parameter in the header, this digest is a SHA256 of room_id cyphered by your api_key as shared secret.

v1 Webhooks

We sign webhooks including a signature in each webhook's bandyer-signature header. This allows to verify that webhooks are sent by Kaleyra and not by a third party.

The bandyer-signature header will be in the form: t=1554193902,v0=ComputedHMAC where v0 is the computed signature.

To compute the signature you must concatenate:

  • t value (as a string)
  • the character .
  • The actual JSON payload (i.e the request body)


Input: 1554193902.{"event":"test"}

You then create an SHA256 HMAC using that string as input and the company apikey as secret key.

secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

Code sample (in NodeJS)

const crypto = require('crypto');

const data = {
  event: 'on_room_deleted',
  event_version: '1.0',
  namespace: 'room',
  timestamp: 1624605171921,
  data: {
     room_id: 'room_5beecf8c0f29',
     deleted_links: [
         { user_id: 'user_1', link: '""' },
         { user_id: 'user_2', link: '""' }
const secret = 'ak_fake_123456789';
const timestamp = '1554297654628';

const bandyerSignature = crypto.createHmac('sha256', secret).update(`${timestamp}.${JSON.stringify(data)}`).digest('hex'));