Webhooks
Recevez des événements Cardencer signés pour vos paiements, remboursements et litiges, vérifiez la signature HMAC-SHA512 et traitez-les de manière idempotente.
Les webhooks informent votre serveur de tout événement concernant un paiement, un remboursement ou un litige : inutile d'interroger l'API en boucle. Chaque envoi est une requête HTTPS POST avec un corps JSON, signée avec votre clé de signature des webhooks.
1. Créez un endpoint#
Exposez un endpoint HTTPS public qui accepte les requêtes POST. Renvoyez un statut 2xx dès que vous avez enregistré l'événement ; effectuez les traitements longs (e-mails, synchronisation ERP) ensuite.
2. Enregistrez l'endpoint#
- Ouvrez le dashboard et rendez-vous dans API keys. Copiez la Webhook signing key affichée sous Webhook verification.
- Envoyez l'URL de votre endpoint au support Cardencer en précisant s'il s'agit de la sandbox ou de la production. Cardencer l'enregistre sur votre profil d'entreprise et vous confirme le démarrage des envois.
Si vous utilisez un plugin, celui-ci affiche sa propre URL de webhook : c'est elle qu'il faut enregistrer.
3. Vérifiez la signature#
Cardencer calcule un HMAC-SHA512 du corps brut exact de la requête avec votre clé de signature des webhooks, et envoie le condensé hexadécimal en minuscules dans l'en-tête X-Webhook-Signature-512.
- Lisez le corps brut avant de le parser.
- Calculez le HMAC-SHA512 du corps brut avec votre clé de signature et encodez-le en hexadécimal.
- Comparez-le à
X-Webhook-Signature-512en temps constant. - Rejetez la requête avec un
401si les valeurs diffèrent ou si l'en-tête est absent.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/webhooks/cardencer", express.raw({ type: "application/json" }), (req, res) => {
const received = req.get("X-Webhook-Signature-512") ?? "";
const expected = crypto.createHmac("sha512", process.env.CARDENCER_WEBHOOK_KEY).update(req.body).digest("hex");
const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString("utf8"));
handleEvent(event); // enregistrez d'abord event.event_id, voir « Doublons et ordre » ci-dessous
res.sendStatus(200);
});
app.listen(3000);import hashlib, hmac, json, os
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/cardencer")
def cardencer_webhook():
raw = request.get_data()
expected = hmac.new(os.environ["CARDENCER_WEBHOOK_KEY"].encode(), raw, hashlib.sha512).hexdigest()
received = request.headers.get("X-Webhook-Signature-512", "")
if not hmac.compare_digest(expected, received):
abort(401)
event = json.loads(raw)
handle_event(event) # enregistrez d'abord event["event_id"]
return "", 200<?php
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha512', $raw, getenv('CARDENCER_WEBHOOK_KEY'));
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_512'] ?? '';
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
handle_event($event);
http_response_code(200);Dépannage :
- La signature ne correspond pas : vous hachez un JSON parsé puis resérialisé. Hachez les octets bruts.
- En-tête absent : vérifiez le nom de l'en-tête (
X-Webhook-Signature-512) et que votre proxy le transmet bien. - Mauvaise clé : la sandbox et la production utilisent des clés de signature différentes.
Contenu d'un événement#
{
"merchant_id": "merchant_1700000000",
"event_id": "evt_018c4f3f6a1d7b2e9c",
"event_type": "payment_succeeded",
"timestamp": "2026-11-20T10:15:03.000Z",
"content": {
"type": "payment_details",
"object": {
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"status": "succeeded",
"amount": 4900,
"amount_received": 4900,
"currency": "EUR",
"customer_id": "cus_58211",
"payment_method_id": "pm_lmTnIO5EdCiiOrRqT2RF",
"updated": "2026-11-20T10:15:02.000Z"
}
}
}content.type vaut payment_details, refund_details ou dispute_details ; content.object contient le paiement, le remboursement ou le litige complet, tel que renvoyé par l'API.
Types d'événements#
| Événement | Quand |
|---|---|
payment_succeeded |
Le paiement est capturé. Traitez la commande. |
payment_failed |
Le paiement a été refusé ou a échoué. |
payment_processing |
L'acquéreur est encore en train de le traiter. |
payment_authorized |
Autorisé et en attente de capture. |
payment_captured |
Une capture manuelle a abouti. |
payment_cancelled |
Le paiement a été annulé avant la capture. |
action_required |
Le client doit effectuer une action, par exemple 3D Secure. |
refund_succeeded |
Un remboursement a abouti. |
refund_failed |
Un remboursement a échoué. |
dispute_opened, dispute_challenged, dispute_won, dispute_lost, dispute_accepted, dispute_expired, dispute_cancelled |
Cycle de vie d'un litige. |
Nouvelles tentatives#
Un envoi est réussi lorsque votre endpoint renvoie un 2xx. Dans le cas contraire, Cardencer effectue 16 nouvelles tentatives sur environ 24 heures :
| Tentative | Délai |
|---|---|
| 1re | 1 minute après la première tentative |
| 2e et 3e | 5 minutes |
| 4e à 8e | 10 minutes |
| 9e à 13e | 1 heure |
| 14e à 16e | 6 heures |
Doublons et ordre#
- Doublons : les nouvelles tentatives peuvent livrer deux fois le même événement. Enregistrez chaque
event_idavant d'agir, et acquittez les doublons sans les traiter à nouveau. - Ordre : les envois peuvent arriver dans le désordre. Pour les paiements, comparez
content.object.updatedavec la valeur enregistrée et n'appliquez que les états plus récents. - Source de vérité : en cas de doute, récupérez l'objet avec
GET /payments/{payment_id}ouGET /refunds/{refund_id}.
Testez les webhooks#
Dans la sandbox, enregistrez une URL de tunnel (par exemple obtenue avec ngrok http 3000) et lancez le paiement du démarrage rapide : vous recevez payment_succeeded en quelques secondes.