Webhooks
Recevez des notifications HTTP en temps réel quand vos certificats sont prêts.
Les webhooks évitent de poller l'API. Dès qu'un certificat est rendu ou qu'un batch se termine, CertifMaker envoie une requête POST vers votre URL.
Configurer un webhook
Depuis le dashboard : Paramètres → Webhooks → Nouveau webhook.
Renseignez :
- Un nom descriptif
- L'URL de votre endpoint
- Les événements à recevoir
Le secret de signature est affiché une seule fois à la création. Stockez-le dans vos variables d'environnement.
Événements disponibles
| Événement | Déclencheur |
|---|---|
certificate.ready | Un certificat a été rendu avec succès (PDF disponible) |
batch.completed | Tous les certificats d'un batch ont été traités |
Format du payload
{
"event": "certificate.ready",
"deliveryId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2026-04-05T10:30:00.000Z",
"data": {
"certificateId": "cert_abc123",
"verificationHash": "a1b2c3d4e5f6...",
"pdfUrl": "https://...",
"imageUrl": "https://...",
"templateId": "tpl_xyz",
"batchId": null,
"recipientName": "Amadou Diallo",
"recipientEmail": "amadou@example.com"
}
}Payload batch.completed
{
"event": "batch.completed",
"deliveryId": "...",
"createdAt": "2026-04-05T10:32:00.000Z",
"data": {
"batchId": "batch_xyz",
"status": "COMPLETED",
"totalCount": 50,
"processedCount": 48,
"failedCount": 2,
"durationMs": 94200
}
}Headers de la requête
| Header | Description |
|---|---|
Content-Type | application/json |
X-CertifMaker-Event | Nom de l'événement (certificate.ready) |
X-CertifMaker-Delivery | UUID unique de la livraison |
X-CertifMaker-Signature | Signature HMAC — voir ci-dessous |
Vérifier la signature
La signature dans X-CertifMaker-Signature est au format sha256=<hmac>.
Calculez le HMAC-SHA256 du corps brut de la requête avec votre secret, puis comparez :
import { createHmac, timingSafeEqual } from "crypto";
function verifyWebhook(secret: string, rawBody: string, signature: string): boolean {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length) return false;
return timingSafeEqual(a, b);
}
// Dans votre handler Express / Next.js
app.post("/webhooks/certifmaker", express.raw({ type: "application/json" }), (req, res) => {
const sig = req.headers["x-certifmaker-signature"] as string;
if (!verifyWebhook(process.env.CERTIFMAKER_WEBHOOK_SECRET!, req.body.toString(), sig)) {
return res.status(401).send("Signature invalide");
}
const payload = JSON.parse(req.body.toString());
if (payload.event === "certificate.ready") {
const { certificateId, pdfUrl } = payload.data;
// Traiter le certificat prêt
}
res.status(200).send("OK");
});Comportement en cas d'échec
CertifMaker effectue 3 tentatives avec un backoff exponentiel (1s, 2s, 4s). Si les 3 tentatives échouent, le webhook est marqué en erreur — visible dans le dashboard. Le compteur d'erreurs se remet à zéro dès qu'une livraison réussit.
Votre endpoint doit retourner un status 2xx dans les 10 secondes pour être considéré comme réussi.
Erreurs
Référence complète des codes d'erreur de l'API CertifMaker.
Générer un certificat
Génère un certificat à partir d'un template. Consomme **1 crédit**. Le rendu PDF est asynchrone — utilisez l'endpoint `GET /certificates/:id` ou un webhook `certificate.ready` pour savoir quand le PDF est disponible.