Webhooks, signatures et nouvelles tentatives
Vérifier le corps brut, gérer les doublons et récupérer les changements avec l’API.
Créez une destination HTTPS dans Paramètres → Développeurs, choisissez les événements et conservez le secret. Utilisez Envoyer un test et contrôlez les livraisons. L’envoi est asynchrone, après validation de la modification métier.
Événements et enveloppe
Les types pris en charge sont student.created, student.updated, enrollment.created, invoice.issued, payment.recorded, payment.refunded, results.published et webhook.test. GET /api/public/v1/events expose le catalogue déployé.
{
"id": "evt_example",
"type": "payment.recorded",
"created_at": "2026-10-23T09:00:00+00:00",
"data": { "payment": { "id": "example", "amount_minor": 10000, "currency": "NGN" } }
}
Cette enveloppe abrégée n’est pas le schéma complet d’un paiement. Les données suivent la représentation publique correspondante. Traitez les identifiants d’événement et de livraison comme des chaînes opaques.
Vérifier avant traitement
L’en-tête X-Takadar-Signature contient t=<horodatage unix>,v1=<empreinte hexadécimale>. Calculez HMAC-SHA256 sur l’horodatage, un point et les octets bruts exacts. Refusez les horodatages hors tolérance de 300 secondes et comparez en temps constant. Ne désérialisez pas le JSON pour le reconstruire avant vérification.
import hashlib
import hmac
import time
def verify_webhook(secret: str, raw_body: bytes, header: str, *, now=None) -> bool:
try:
parts = dict(part.split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
presented = parts["v1"]
except (ValueError, KeyError):
return False
current = time.time() if now is None else now
if abs(current - timestamp) > 300:
return False
signed = str(timestamp).encode("ascii") + b"." + raw_body
expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, presented)
Lisez le corps brut avant sa transformation par le framework. Après vérification, mettez l’événement en file durablement et répondez avec succès. Exécutez le travail lent séparément.
Gérer doublons et récupération
Dédupliquez selon l’identifiant de l’événement. L’en-tête de livraison identifie l’envoi ; l’identifiant d’événement évite la répétition de l’effet métier. Prévoyez rejeux et résultats réseau ambigus.
Le worker autorise jusqu’à six tentatives espacées. Dix livraisons consécutives épuisant leurs tentatives désactivent la destination ; une réussite remet le compteur à zéro. Corrigez la cause, puis utilisez rejeu ou réactivation autorisés. Une rotation remplace le secret : coordonnez le récepteur.
Interroger aussi l’API
Un import groupé ne produit pas un événement par étudiant. Aucun rejeu par plage de dates n’est disponible ; le rejeu vise chaque livraison. Combinez les webhooks avec le filtre de modification inclusif et un rapprochement périodique.
En production, la destination doit utiliser HTTPS et une adresse publique. Les adresses privées ou locales sont refusées, le DNS est contrôlé à l’envoi et les redirections ne sont pas suivies. Enregistrer une URL ne prouve pas sa joignabilité ni sa livraison.