Commencer gratuitement
14 jours d'essai gratuit - sans carte bancaire
Hisab
Tarifs
Ventes : +212 649 22 43 64
Commencer gratuitement

14 jours d'essai gratuit - sans carte bancaire

Connexion
Guide Webhooks

Documentation Webhooks

Recevez des notifications en temps réel lorsque des événements se produisent dans votre compte Hisab. Construisez des intégrations réactives avec les événements webhook.

Aperçu

Les webhooks permettent à votre application de recevoir des notifications HTTP en temps réel lorsque des événements se produisent dans votre compte Hisab. Au lieu d'interroger l'API pour les changements, les webhooks envoient les données à votre serveur au fur et à mesure.

Comment fonctionnent les webhooks

1
Enregistrer un point de terminaison webhook

Configurez une URL dans votre tableau de bord Hisab où vous souhaitez recevoir les événements webhook. Votre point de terminaison doit utiliser HTTPS.

2
Sélectionner les événements à recevoir

Choisissez les événements pour lesquels vous souhaitez recevoir des notifications (ex: invoice.finalized, customer.created).

3
Recevoir et traiter les événements

Lorsqu'un événement se produit, Hisab envoie une requête HTTP POST à votre point de terminaison avec les données de l'événement. Vérifiez la signature et traitez l'événement.

Tester les webhooks

Utilisez des services comme webhook.site ou ngrok pour tester les webhooks pendant le développement. Vous pouvez également utiliser la fonction de test webhook dans votre tableau de bord Hisab pour envoyer des événements exemples.

Types d'événements

Abonnez-vous aux événements qui comptent pour votre intégration. Chaque événement représente une action spécifique qui s'est produite dans votre compte Hisab.

Invoice Events

invoice.created

When a new invoice is created (draft status)

invoice.updated

When an invoice is modified

invoice.finalized

When an invoice is finalized and assigned an official number

invoice.sent

When an invoice is sent to the customer via email

invoice.paid

When an invoice is marked as paid

invoice.voided

When an invoice is voided/cancelled

Customer Events

customer.created

When a new customer is added

customer.updated

When customer information is modified

customer.deleted

When a customer is deleted

Charges utiles Webhook

Toutes les charges utiles webhook suivent une structure cohérente. Le champ data contient les informations spécifiques à l'événement.

En-têtes HTTP

HTTP Headers
POST /webhooks/hisab HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-Hisab-Signature: a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0
X-Hisab-Timestamp: 1732713000000
X-Hisab-Event: invoice.finalized
X-Hisab-Delivery-ID: del_abc123
User-Agent: Hisab-Webhook/1.0

Structure de la charge utile

Example Payload
{
  "id": "evt_1234567890",
  "type": "invoice.finalized",
  "created": "2025-11-27T14:30:00Z",
  "data": {
    "id": "inv_abc123",
    "invoice_number": "INV-2025-00042",
    "status": "finalized",
    "customer_id": "cus_xyz789",
    "customer_name": "ACME Corporation",
    "currency": "MAD",
    "subtotal": "5000.00",
    "total_tax": "1000.00",
    "total": "6000.00",
    "issue_date": "2025-11-27",
    "due_date": "2025-12-27",
    "finalized_at": "2025-11-27T14:30:00Z",
    "items": [
      {
        "description": "Web Development Services",
        "quantity": "10",
        "unit_price": "500.00",
        "tax_rate": "20",
        "total": "6000.00"
      }
    ]
  },
  "organization_id": "org_123456"
}

Champs de la charge utile

idstringIdentifiant unique pour cet événement
typestringLe type d'événement (ex: invoice.finalized)
createdstringHorodatage ISO 8601 de la création de l'événement
dataobjectLes données de l'événement contenant l'objet concerné
organization_idstringL'identifiant de votre organisation

Vérification des signatures

Chaque requête webhook inclut une signature dans l'en-tête X-Hisab-Signature. Vérifiez toujours cette signature pour vous assurer que le webhook provient de Hisab et n'a pas été altéré.

Avertissement de sécurité

Ne sautez jamais la vérification de signature en production. Sans elle, des acteurs malveillants pourraient envoyer de faux événements webhook à votre point de terminaison.

Comment vérifier les signatures

  1. Extraire les en-têtes X-Hisab-Signature et X-Hisab-Timestamp de la requête
  2. Concaténer l'horodatage et le corps de la requête avec un point: timestamp.body
  3. Calculer un hash HMAC-SHA256 en utilisant votre secret webhook
  4. Comparer le hash calculé avec l'en-tête de signature en utilisant une comparaison à temps constant
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post('/webhooks/hisab', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hisab-signature'];
  const timestamp = req.headers['x-hisab-timestamp'];
  const payload = req.body.toString();

  // Verify timestamp is recent (within 5 minutes)
  const timestampAge = Date.now() - parseInt(timestamp);
  if (timestampAge > 300000) {
    return res.status(400).send('Timestamp too old');
  }

  // Verify signature
  const signedPayload = `${timestamp}.${payload}`;
  if (!verifyWebhookSignature(signedPayload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  // Handle the event
  switch (event.type) {
    case 'invoice.finalized':
      handleInvoiceFinalized(event.data);
      break;
    case 'invoice.paid':
      handleInvoicePaid(event.data);
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});

Politique de réessai

Si votre point de terminaison ne répond pas avec un code de statut 2xx, Hisab réessaiera la livraison du webhook en utilisant une stratégie d'attente exponentielle.

Livraison réussie

Retournez un code de statut 2xx dans les 30 secondes pour accuser réception

HTTP 2xx
Livraison échouée

Les réponses 4xx, 5xx ou les timeouts déclencheront des réessais automatiques

HTTP 4xx, 5xx, timeout

Calendrier des réessais

Tentative 1Immédiatement
Tentative 2Après 5 minutes
Tentative 3Après 30 minutes
Tentative 4Après 2 heures
Tentative 5Après 24 heures

Bonnes pratiques

Toujours vérifier les signatures

Validez l'en-tête X-Hisab-Signature à chaque requête pour garantir l'authenticité et prévenir les attaques d'usurpation.

Répondre rapidement

Retournez une réponse 2xx dans les 30 secondes. Traitez l'événement de manière asynchrone si nécessaire pour éviter les timeouts.

Gérer l'idempotence

Stockez les IDs d'événements traités pour gérer gracieusement les livraisons en double. Le même événement peut être livré plusieurs fois.

Utiliser des files d'attente en arrière-plan

Pour un traitement complexe, accusez réception du webhook immédiatement et ajoutez l'événement à une file d'attente de tâches en arrière-plan.

Sécuriser votre point de terminaison

Utilisez uniquement HTTPS. Optionnellement, ajoutez une liste blanche d'IP ou une authentification supplémentaire pour plus de sécurité.