VPOS.am Webhooks: événements de paiement signés

Webhooks

Vérifiez X-VPOS-Signature sur le corps brut, conservez l’event id, renvoyez rapidement 2xx et traitez les livraisons répétées de façon idempotente.

Version

API v1

Dernière révision

16 sept. 2026

État

Contrat publié

Vue d’ensemble

Le contrat webhook public de VPOS.am livre l’événement signé payment.status_changed avec un statut de paiement vérifié côté serveur.

HTTP / HMAC

Contrat de signature

Vérifiez le HMAC horodaté sur le corps brut de la requête avant d’analyser le payload ou de modifier l’état métier.

X-VPOS-Event-Id: <event_id>
X-VPOS-Event-Type: payment.status_changed
X-VPOS-Webhook-Timestamp: <unix_timestamp>
X-VPOS-Signature: t=<unix_timestamp>,v1=<current_secret_hmac>[,v1=<grace_secret_hmac>]

signed_payload = <timestamp>.<raw_request_body>
signature = HMAC-SHA256(webhook_secret, signed_payload)

Champ	Contrat
En-tête	`X-VPOS-Signature`
Valeur signée	`<timestamp>.<raw_request_body>`
Algorithme	`HMAC-SHA256`
Tolérance du timestamp	`5 minutes`
Délai de livraison	`5 secondes`
Nombre maximal de tentatives par défaut	`8 tentatives`
Planification des relances	`Exponentielle à partir de 30 secondes, plafonnée à 1 heure`
Accusé de réception	`Renvoyer rapidement une réponse 2xx`
Rotation du secret	`L’en-tête peut contenir plusieurs valeurs v1. N’acceptez l’événement que si au moins une correspond au secret actuel ou à un secret de grâce non expiré.`
Traitement	`Vérifiez la signature, conservez l’event id, puis mettez les effets secondaires en file.`

Contrat public de l’événement

Seul payment.status_changed est actuellement documenté publiquement. fiscalStatus fait partie de data.payment, sans promettre des événements publics fiscal ou reconciliation séparés.

Signature et nouvelle livraison

Calculez HMAC-SHA256 sur <timestamp>.<raw_request_body> avec le merchant webhook secret, refusez les timestamps anciens et exécutez les actions downstream dans une queue idempotente.

Comment utiliser cette page

Webhooks aide à aligner le scénario de paiement entre métier, développement et opérations. Avant le lancement, il faut fixer le canal de vente, la route fournisseur, les responsables webhook, la vérification du statut et le support client après paiement.