Webhooks

Des événements qui viennent à vous

Hisab signe et livre les événements factures et clients à votre endpoint, avec relances automatiques. Tout se configure depuis le tableau de bord.

9types d'événements|HMAC-SHA256

Mise en place

Les webhooks se gèrent entièrement depuis le tableau de bord. Aucun appel API n'est nécessaire pour en créer un.

1
Dans le tableau de bord, ouvrez Paramètres puis Webhooks, et ajoutez votre endpoint HTTPS.
2
Choisissez les événements à recevoir et copiez le secret de signature. Il servira à vérifier les livraisons.
3
Répondez 2xx rapidement depuis votre endpoint. Tout autre résultat est considéré comme un échec et relancé.

Professional inclut 10 endpoints webhook ; Fiduciaire n'a pas de limite. Vous pouvez mettre en pause un endpoint, faire tourner son secret ou rejouer les livraisons échouées depuis le tableau de bord.

Événements

Neuf types d'événements sont émis aujourd'hui, couvrant le cycle de vie des factures et les changements clients.

`invoice.created`	Un brouillon de facture a été créé
`invoice.updated`	Un brouillon de facture a été modifié
`invoice.finalized`	Une facture a reçu son numéro officiel
`invoice.sent`	Une facture a été marquée envoyée
`invoice.paid`	Une facture a été marquée payée
`invoice.voided`	Une facture a été annulée
`customer.created`	Un client a été créé
`customer.updated`	Un client a été modifié
`customer.deleted`	Un client a été archivé

Payload

Les livraisons sont des POST JSON portant le nom de l'événement, l'instantané de la ressource, l'identifiant de votre organisation et l'heure d'émission :

delivery

POST https://example.ma/hisab-webhook
Content-Type: application/json
X-Webhook-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-Webhook-Timestamp: 1780750800
X-Webhook-Event: invoice.paid
X-Webhook-Delivery-Id: del_3f8c2a91
User-Agent: Hisab-Webhooks/1.0

{
  "event": "invoice.paid",
  "data": {
    "id": "inv_8f3a91",
    "invoice_number": "FAC-2026-0142",
    "status": "paid",
    "total": "12480.00"
  },
  "organization_id": "org_4d11a7",
  "created_at": "2026-06-05T14:00:00Z"
}

`event`	string
`data`	object
`organization_id`	string
`created_at`	datetime (ISO 8601)

Signatures

Chaque livraison est signée avec le secret de votre endpoint : HMAC-SHA256 sur le timestamp, un point, et le corps brut. Vérifiez toujours avant de faire confiance au payload.

X-Webhook-Signature: v1=HMAC_SHA256(secret, timestamp + "." + payload)

Node.js

import { verifyWebhookSignature } from 'hisab-sdk';

export async function POST(req: Request) {
  const payload = await req.text();

  const valid = verifyWebhookSignature({
    payload,
    signature: req.headers.get('x-webhook-signature')!,
    timestamp: req.headers.get('x-webhook-timestamp')!,
    secret: process.env.HISAB_WEBHOOK_SECRET!,
  });

  if (!valid) return new Response('Invalid signature', { status: 401 });
  return new Response('ok');
}

Comparez les signatures avec une fonction à temps constant (le SDK et les exemples ci-dessus le font) et rejetez les timestamps de plus de 5 minutes pour bloquer les attaques par rejeu.

Relances

Une livraison réussit sur toute réponse 2xx en moins de 30 secondes. Sinon, elle est retentée jusqu'à 5 fois avec des délais croissants :

Tentative	Délai
1	~1 min
2	~5 min
3	~15 min
4	~1 h
5	~4 h

Les délais portent environ 20 % d'aléa (jitter), les heures exactes varient donc. Après le cinquième échec, la livraison est marquée échouée ; vous pouvez la rejouer manuellement depuis le tableau de bord.

Bonnes pratiques

Vérifiez chaque signature
Rejetez tout ce qui échoue à la vérification. Cela ne vient pas de Hisab.
Répondez vite
Accusez réception en 2xx avant tout traitement lourd ; la livraison expire après 30 secondes.
Dédupliquez avec l'identifiant de livraison
Les relances réutilisent l'en-tête X-Webhook-Delivery-Id. Stockez-le et ignorez ce qui est déjà traité.
Mettez le travail lourd en file
Poussez l'événement vers une file ou un job d'arrière-plan plutôt que de le traiter en ligne.
Protégez le secret
Stockez-le comme un mot de passe et faites-le tourner depuis le tableau de bord en cas de fuite.