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.
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.
Configurez une URL dans votre tableau de bord Hisab où vous souhaitez recevoir les événements webhook. Votre point de terminaison doit utiliser HTTPS.
Choisissez les événements pour lesquels vous souhaitez recevoir des notifications (ex: invoice.finalized, customer.created).
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.
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.
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.createdWhen a new invoice is created (draft status)
invoice.updatedWhen an invoice is modified
invoice.finalizedWhen an invoice is finalized and assigned an official number
invoice.sentWhen an invoice is sent to the customer via email
invoice.paidWhen an invoice is marked as paid
invoice.voidedWhen an invoice is voided/cancelled
customer.createdWhen a new customer is added
customer.updatedWhen customer information is modified
customer.deletedWhen a customer is deleted
Toutes les charges utiles webhook suivent une structure cohérente. Le champ data contient les informations spécifiques à l'événement.
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{
"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"
}idstringIdentifiant unique pour cet événementtypestringLe type d'événement (ex: invoice.finalized)createdstringHorodatage ISO 8601 de la création de l'événementdataobjectLes données de l'événement contenant l'objet concernéorganization_idstringL'identifiant de votre organisationChaque 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é.
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.
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');
});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.
Retournez un code de statut 2xx dans les 30 secondes pour accuser réception
HTTP 2xxLes réponses 4xx, 5xx ou les timeouts déclencheront des réessais automatiques
HTTP 4xx, 5xx, timeoutValidez l'en-tête X-Hisab-Signature à chaque requête pour garantir l'authenticité et prévenir les attaques d'usurpation.
Retournez une réponse 2xx dans les 30 secondes. Traitez l'événement de manière asynchrone si nécessaire pour éviter les timeouts.
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.
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.
Utilisez uniquement HTTPS. Optionnellement, ajoutez une liste blanche d'IP ou une authentification supplémentaire pour plus de sécurité.