Webhook (notifications HTTP)

Kash.click supporte deux familles de webhooks : les webhooks historiques, conserves pour retrocompatibilite, et les webhooks JSON nouvelle generation destines aux integrations Zapier, Make, n8n, Pipedream ou a vos propres services.

Webhooks JSON nouvelle generation

Chaque livraison est envoyee en POST avec un corps JSON stable et des headers de signature. Les donnees sensibles inutiles ne sont pas exposees dans les objets client, produit et fermeture de caisse.

Enveloppe JSON commune

{ "id": "evt_6e6f9d9e7c7c4d71b97c2f51", "type": "sale.created", "created_at": "2026-07-16T10:00:00Z", "account_id": 123, "data": {  "sale": {   "id": 98765,   "number": 42,   "total": 59.9,   "paid": 59.9,   "is_refund": false,   "cashbox_id": 7,   "delivery_method": "Counter sale"  },  "customer": {   "id": 456,   "name": "Martin",   "surname": "Julie",   "email": "julie@example.com"  },  "items": [],  "payments": [],  "invoice": {   "id": 98765,   "number": 42,   "pdf_url": "https://php7.enregistreuse.fr/workers/webpages/downloadInvoice.php?idcommande=98765&verif=..."  } }}

Headers envoyes

Verification de signature

La signature est calculee avec le secret partage du webhook, sur le timestamp, un point, puis le corps JSON brut exactement recu.

expected = "v1=" + hex_hmac_sha256(X-Kash-Timestamp + "." + raw_body, webhook_secret)

$timestamp = $_SERVER["HTTP_X_KASH_TIMESTAMP"];$signature = $_SERVER["HTTP_X_KASH_SIGNATURE"];$body = file_get_contents("php://input");$expected = "v1=".hash_hmac("sha256", $timestamp.".".$body, $secret);if (!hash_equals($expected, $signature)) {  http_response_code(401);  exit;}if (abs(time() - intval($timestamp)) > 300) {  http_response_code(401);  exit;}

Types d'evenements disponibles

Details des objets data

Fiabilite et retries

• Une reponse HTTP 2xx marque la livraison comme success.
• Les autres reponses ou erreurs reseau restent en pending jusqu'a la prochaine tentative.
• Les delais de retry sont 1 minute, 5 minutes, 15 minutes, 1 heure, puis 6 heures.
• Apres 5 tentatives, la livraison passe en failed.
• Chaque tentative stocke la date, le code HTTP, un extrait de reponse et le message d'erreur.

Webhooks historiques

Les anciens champs saleWebhookURL et openingWebhookURL restent supportes. Ils envoient des formulaires application/x-www-form-urlencoded et ne remplacent pas les webhooks JSON nouvelle generation.

Webhook historique de commande

L'URL configuree pour les ventes est appelee lors d'une commande validee ou terminee.

• type : validated ou terminated
• isRefund : true/false si remboursement
• orderID : numero comptable de commande
• orderInternalID : identifiant interne de commande
• creationDate, validationDate, valueDate : dates en timestamp
• price, paid : montants de la commande
• clientID, client : identifiant et JSON client
• cashBoxID, deliveryMethod : caisse et livraison
• PDFinvoice : lien de facture PDF
• items, VATs, VAT, payments : JSON articles, TVA et paiements
• HMAC_SHA256, signatureVerificationURL : signature historique et URL de verification

Webhook historique d'ouverture / fermeture de caisse

L'URL configuree pour les ouvertures et fermetures de caisse est appelee lors des changements d'etat de caisse.

• type : cashBox_close ou cashBox_open
• total : total encaisse sur la periode, pour cashBox_close
• opened, closed : dates d'ouverture et fermeture
• signatureVerificationURL : URL permettant de verifier la signature historique