Intégration webhook
Un webhook signale un événement à votre URL. Vérifiez l’état de référence par GET transaction.
Configurer le destinataire
Dans Heth, définissez une URL que vous contrôlez, le secret et activez la livraison. Modifier l’URL change le destinataire des événements du compte. Protégez l’endpoint et évitez les redirections vers des tiers. La configuration nécessite la session utilisateur ; la clé transactionnelle ne suffit pas automatiquement.
Traiter les événements
- Vérifiez signature et protection contre les répétitions selon le contrat ci-dessous.
- Enregistrez les identifiants sans champs sensibles.
- Traitez de façon idempotente : une livraison double ou tardive ne doit pas créer de paiement.
- Récupérez la transaction avec vos identifiants et rapprochez le statut.
- Retournez la réponse prévue par le contrat de livraison.
Une notification push n’est pas un webhook et ne garantit pas la livraison. Cet aperçu ne promet ni ordre, ni intervalles de répétition, ni authentification identique pour toutes les intégrations. Obtenez le contrat effectif avant l’automatisation en production.
Format du webhook du compte
Ce format concerne les webhooks configurés dans Heth. Les autres callbacks peuvent différer.
Avec un secret non vide, les en-têtes comprennent x-webhook-signature (HMAC-SHA256 hex), x-webhook-timestamp (secondes Unix) et x-webhook-event-id. Vérifiez le HMAC de timestamp + "." + les octets HTTP bruts avec le secret ; ne re-sérialisez pas le JSON avant vérification. Comparez timestamp du corps signé et en-tête, refusez un écart supérieur à 5 minutes, comparez la signature en temps constant et dédupliquez par event_id. Les répétitions conservent event_id avec nouvel horodatage/signature. Sans secret, les en-têtes de signature peuvent manquer ; définissez le secret avant automatisation.
hex(HMAC-SHA256(secret, timestamp + "." + raw_body))
L’enveloppe contient event_id, timestamp, type et data. Les événements de transaction comprennent tx_id, txid, type, status, amount, currency et event_type. amount peut être un entier JSON : utilisez un parseur sans perte. donation peut s’ajouter pour un don. Après vérification et enregistrement, répondez HTTP 2xx ; une event_id vérifiée répétée ne doit pas répéter l’action. Confirmez toujours la transaction par GET.