Webhooks

Configurez un notify_url HTTPS public lors de la création de votre paiement ou dans la configuration Hosted Checkout. Utilisez une URL stable, sans localhost, adresse privée ou destination interne : ces destinations sont bloquées au moment de la livraison.

Où trouver le secret webhook ?

Dans votre tableau de bord, ouvrez Clé API → Direct API → Secret webhook, puis cliquez sur Afficher ou générer le secret. S’il n’existe pas encore, il est créé à ce moment-là. Cette section nécessite un compte KYC validé et l’accès Direct API activé. Copiez la valeur whsec_... dans la variable d’environnement ASHTECH_WEBHOOK_SECRET de votre serveur. Ne l’envoyez pas à votre agent dans un message et ne l’ajoutez jamais au code navigateur ou à Git. Si vous le régénérez, l’ancien secret est immédiatement invalide : mettez à jour la variable sur votre serveur avant de traiter les prochaines notifications. AshTech Pay envoie les notifications avec ces headers :

X-Ashtech-Event-Id: id-de-livraison
X-Ashtech-Timestamp: 1735643554
X-Ashtech-Signature: sha256=...

Les notifications sont mises en file avant livraison, dédupliquées par transaction et événement, et signées avec votre secret webhook whsec_.... Si aucun secret webhook n’est configuré, la livraison n’est pas envoyée : elle reste en attente et réessaie périodiquement jusqu’à la configuration du secret.

HMAC-SHA256(webhook_secret, timestamp + "." + raw_request_body)

La vérification doit utiliser le corps brut avant le parsing JSON. Refusez les timestamps trop anciens et dédupliquez avec X-Ashtech-Event-Id ou transaction_id.

Bon traitement d’un webhook

Répondez rapidement avec un statut HTTP 2xx.
Vérifiez toujours la signature avec votre secret configuré.
Rendez le traitement idempotent avec l’identifiant de transaction et votre référence.
Rechargez le statut côté serveur avant de créditer ou livrer.
Traitez les événements en double sans créer deux commandes.

Exemple Express :

app.post("/webhooks/ashtechpay", express.raw({ type: "application/json" }), async (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.header("X-Ashtech-Timestamp") || "";
  const signature = req.header("X-Ashtech-Signature") || "";

  // Vérifier HMAC-SHA256(secret, timestamp + "." + rawBody)
  if (!isValidAshtechSignature(rawBody, timestamp, signature, process.env.ASHTECH_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(rawBody);

  // Accuser réception rapidement.
  res.sendStatus(200);

  if (event.status !== "completed") {
    return;
  }

  // Vérifier l'événement puis traiter votre commande une seule fois.
  await fulfillOrderOnce(event.reference, event.transaction_id);
});

Ne faites pas confiance au navigateur

Une page de succès peut être fermée, rejouée ou modifiée. Utilisez le webhook ou une vérification serveur de GET /v1/transaction/:id?user_id=VOTRE_USER_ID pour confirmer le paiement. Les erreurs HTTP, les erreurs réseau et les réponses non-2xx sont réessayées avec un délai croissant, jusqu’à huit tentatives avant l’échec permanent. Les notifications restent dédupliquées : rendez votre traitement idempotent.

Conservez les payloads reçus et les réponses de votre traitement pendant la durée nécessaire à votre support et à vos rapprochements comptables.

Démarrer

Checkout

Integration

Direct API

Référence

Ressources

Où trouver le secret webhook ?

Bon traitement d’un webhook

Ne faites pas confiance au navigateur

​Où trouver le secret webhook ?

​Bon traitement d’un webhook

​Ne faites pas confiance au navigateur

Où trouver le secret webhook ?

Bon traitement d’un webhook

Ne faites pas confiance au navigateur