Signature Verification

How to handle signed requests from Web Hooks.

Because your webhook URL needs to be public to accept requests from Tidy, it is at risk of receiving fraudulent data from a malicious actor.

To counter this, each webhook request from Tidy includes a Tidy-Signature header that you can use alongside your webhook's unique signing key to verify that the contents of the request are unmodified and authentic.

A Tidy-Webhook-ID header is also included, which uniquely identifies the specific webhook if you have multiple sending to the same URL, this code is present on the list of webhooks page. You can use this header to decide which signing key to use to verify the message, but if verification succeeds, you should also check that the Tidy-Webhook-ID matches the webhook_id attribute in the message body.

The contents of the header currently look like this: t=unixtime,v1=hexsignature.

Make sure you parse out the t and v1 elements using a method that is tolerant for different key orderings and new uniquely-keyed elements to also be included, to ensure that future additions to the header do not break your code. i.e. split them by the , character, then the = character instead of relying on any fixed-length parsing or brittle order-dependent regexes.

As an example, to verify a signature with a five minute grace period would look like so:

require 'base64'
require 'openssl'
require 'json'

tolerance = 300 # 5 minutes
recieved_via_http_method = 'POST'
webhook_id_on_record = 'ff434f3g4t4y2'

payload = '{"message":"my webhook message"}'
header = 't=1677726570,v1=d8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d'
secret = Base64.strict_decode64(

# ['t=1677726570', 'v1=d8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d']
signature_elements = header.split(',')

# [['t', '1677726570'], ['v1', 'd8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d']]
element_pairs = { |e| e.split('=') } 

# {'t'=>'1677726570', 'v1'=>'d8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d'}
elements = element_pairs.to_h

timestamp = elements['t'].to_i # 1677726570

# 'd8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d'
signature = elements['v1'] 

# '1677726570.{"message":"my webhook message"}'
timestamped_payload = "#{timestamp}.#{payload}"

# 'd8ddb065d5ff7f74274c22161a8c45a1bd192ac4e97b92d0ce76a29af71b271d'
expected_sig = OpenSSL::HMAC.hexdigest('sha256'), secret, timestamped_payload)

if signature != expected_sig # false

if timestamp < - tolerance # false

data = JSON.parse(payload) # decode the payload now its verified

if data['webhook_id'] != webhook_id_on_record 
  || data['http_method'] != recieved_via_http_method # false
import { createHmac } from 'crypto'

// based on
// see LICENSE for more details

const verifySignature = (
  tidySignatureHeader: string,
  signingKeyB64: string,
  body: string,
  registeredWebhookId: string,
  httpMethod: string
) => {
  const signingKey = Buffer.from(signingKeyB64, 'base64')
  const details = parseHeader(tidySignatureHeader, 'v1')
  const tolerance = 300

  if (!details || details.timestamp === -1) {
    throw new Error('Unable to extract timestamp and signatures from header')

  if (!details.signatures.length) {
    throw new Error('No signatures found with expected scheme')

  const timestamp = details.timestamp
  const signature = details.signatures[0]

  const timestampedPayload = `${timestamp}.${body}`

  const expectedSignature = createHmac('sha256', signingKey)
    .update(timestampedPayload, 'utf8')

  if (signature !== expectedSignature) {
    throw new Error('Signature mismatch')

  const timestampAge = Math.floor( / 1000) - timestamp

  if (tolerance > 0 && timestampAge > tolerance) {
    throw new Error('Timestamp outside the tolerance zone')

  const data = JSON.parse(body)

  if (data.webhook_id !== registeredWebhookId) {
    throw new Error(
      `There has been a webhook ID mismatch, expected ${registeredWebhookId} got ${data.webhook_id}`

  if (data.http_method !== httpMethod) {
    throw new Error(
      `There has been a HTTP method mismatch, expected ${httpMethod} got ${data.http_method}`

  return data

const parseHeader = (header: string | null | undefined, scheme: string) => {
  if (typeof header !== 'string') {
    return null

  return header.split(',').reduce(
    (accum, item) => {
      const kv = item.split('=')

      if (kv[0] === 't') {
        accum.timestamp = parseInt(kv[1], 10)

      if (kv[0] === scheme) {

      return accum
      timestamp: -1,
      signatures: [] as string[],