Webhooks

Le webhook est la seule façon fiable d'apprendre qu'un paiement a abouti. Tout le reste — interroger en boucle, faire confiance au 201 — vous fera livrer trop tôt ou trop tard.

Déclarer un endpoint

Depuis la console, onglet Webhooks. Un secret de signature whsec_… s'affiche une seule fois.

Vérifier la signature

Chaque appel porte :

Valsoria-Signature: t=1755770000,v1=<hmac-sha256 hexadécimal>
Valsoria-Event-Id: evt_...

La signature porte sur t + "." + corps, pas sur le corps seul : sans l'horodatage dans le message signé, un ancien appel authentique pourrait être rejoué en changeant simplement le t affiché.

import { ValsoriaPay } from '@valsoria/pay';

const evenement = await ValsoriaPay.webhooks.construireEvenement({
  corpsBrut: req.body.toString('utf8'),
  signature: req.header('Valsoria-Signature'),
  secret: process.env.VALSORIA_WEBHOOK_SECRET,
});

Les trois règles, par ordre d'importance

1. Vérifiez la signature avant de lire le contenu. Votre endpoint est une URL publique. Sans vérification, n'importe qui vous annonce un paiement réussi — et vous livrez.

2. Signez sur le corps BRUT. Un corps re-sérialisé après JSON.parse change d'un octet — ordre des clés, espaces — et la signature porte sur les octets reçus. Avec Express, express.raw({ type: 'application/json' }), jamais express.json. C'est de loin la première cause d'échec de vérification.

3. Dédupliquez sur id. La livraison est « au moins une fois » : un même événement peut arriver deux fois, un simple retard réseau suffit.

Répondre

Répondez 2xx dès que l'événement est enregistré, pas quand il est traité. Un traitement long derrière un webhook finit en délai dépassé, donc en nouvelle tentative, donc en doublon.

Votre réponse	Ce que nous faisons
`2xx`	Terminé.
`410 Gone`	Terminé : vous déclarez que l'endpoint n'existe plus.
Autre code, ou rien	Nouvelle tentative, avec un délai croissant.

Quand ça ne répond plus

Après épuisement des tentatives, la livraison est abandonnée. Au bout de plusieurs abandons, l'endpoint est désactivé — et une alerte apparaît dans votre console, sur tous les écrans.

Nous ne vous prévenons pas par webhook, pour une raison évidente : l'événement partirait vers l'endpoint qui vient d'être désactivé.

Une fois l'adresse corrigée et réactivée, le bouton Tout rejouer relance en une fois toutes les livraisons en échec. Seuls les couples (événement, endpoint) dont la dernière tentative a échoué repartent : cliquer deux fois ne livre pas deux fois.

La charge utile

{
  "id": "evt_9xK2...",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-08-25",
  "created_at": "2026-08-26T09:13:02.114Z",
  "livemode": false,
  "data": { }
}

Version d'API 2026-08-25 · changements · spécification OpenAPI

Démarrer

API