Guide

Vérifier les signatures

Vérifiez l’origine et l’intégrité de chaque webhook avant de le traiter.

Sur cette page

En-têtes de livraison Calcul de la signature Exemple Node.js / TypeScript Traiter un message vérifié

En-têtes de livraison

Chaque livraison est une requête POST vers l’URL enregistrée.

HTTP headers

Content-Type: application/json
X-Kawlya-Event: reservation.created
X-Kawlya-Delivery: evt_3f2504e0-4f89-11e0-b923-1231390215b1
X-Kawlya-Signature: t=1751234567,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Calcul de la signature

La signature utilise HMAC-SHA256 avec le secret de l’abonnement. Le message signé est le timestamp t, un point, puis le corps brut exact de la requête. Comparez les signatures en temps constant et vérifiez l’âge du timestamp.

Signature

HMAC-SHA256(secret, "${t}.${body}")

Exemple Node.js / TypeScript

verify-kawlya-signature.ts

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyKawlyaSignature(
  header: string,
  rawBody: string,
  secret: string,
  toleranceSec = 300,
): boolean {
  const match = header.match(/^t=(\d+),v1=([0-9a-f]{64})$/)
  if (!match) return false
  const [, timestamp, signature] = match
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) {
    return false
  }
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex')
  return timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex'),
  )
}

Traiter un message vérifié

Refusez les signatures invalides avant toute action métier. Après vérification, parsez le JSON et utilisez l’identifiant de livraison pour détecter les doublons. Les nouvelles tentatives réutilisent cet identifiant.

Mis à jour le 21 septembre 2026