Lorsqu’un événement survient sur un paiement, l’API Alma peut notifier le serveur du marchand.
Ce mécanisme est particulièrement important pour les intégrations par redirection, dans lesquelles le client est redirigé vers une page de paiement hébergée par Alma. Il permet de confirmer la commande même si le client ferme la page de paiement avant d’être redirigé vers votre site.
Les notifications sont envoyées de manière asynchrone après le traitement du paiement. Elles peuvent être renvoyées si votre serveur ne répond pas ou renvoie un code HTTP différent de 2xx.
Nouveau système de webhooks
Alma propose un nouveau système de webhooks, actuellement disponible en bêta. Il permet de s’abonner aux événements suivants :
Ces notifications sont envoyées via des requêtes HTTP POST. Elles contiennent une enveloppe structurée ainsi qu’un code identifiant l’événement. Elles sont transmises presque instantanément, contrairement aux IPN historiques qui sont envoyées environ 60 secondes après le paiement.
Pour activer ce système, contactez [email protected] avec ces informations:
- Identifiant marchand ( Disponible dans Paramètres > Configuration API )
- L'url qui recevra les webhooks
- Les type d'événements à envoyer
- Est-ce qu'il faut l'activer sur l'environnement de test, celui de production, ou les deux ?
Vérifier la signature des webhooks
Chaque requête de webhook contient un en-tête X-Alma-Signature. Pour les nouveaux webhooks POST, cet en-tête contient un JWT signé avec l’algorithme RS256 à l’aide d’une clé privée Alma.
Le champ kid présent dans l’en-tête du JWT identifie la clé publique Alma utilisée pour vérifier la signature. Le JWT contient notamment les claims suivants :
| Claim | Description |
|---|---|
body_sha256 | Empreinte SHA-256, encodée en hexadécimal, du corps brut de la requête |
aud | URL du webhook configurée pour l’abonnement |
iat | Date et heure d’émission de la signature |
exp | Date et heure d’expiration de la signature, cinq minutes après iat |
jti | Identifiant unique de la signature |
Pour vérifier la signature :
-
Récupérez les clés publiques d’Alma via l’endpoint JWKS :
GET https://api.almapay.com/v1/webhooks/jwksVous pouvez mettre la réponse en cache. Le cache doit toutefois être renouvelé périodiquement afin de prendre en compte une éventuelle rotation des clés.
-
Décodez le JWT présent dans l’en-tête
X-Alma-Signature. -
Utilisez le champ
kidpour sélectionner la clé publique correspondante. -
Vérifiez la signature du JWT avec l’algorithme
RS256. -
Vérifiez que le claim
audcorrespond exactement à l’URL de votre webhook. -
Vérifiez que le claim
expn’est pas dépassé. -
Calculez l’empreinte SHA-256 du corps brut de la requête et vérifiez qu’elle correspond à la valeur du claim
body_sha256.
Si l’une de ces vérifications échoue, rejetez la requête et ne traitez pas le payload.
Exemple
import hashlib
import httpx
from jose import jwt
JWKS_URL = "https://api.almapay.com/v1/webhooks/jwks"
YOUR_WEBHOOK_URL = "https://your-domain.com/webhooks/alma"
# Récupérez les clés périodiquement et renouvelez-les pour prendre
# en compte une éventuelle rotation des clés.
jwks = httpx.get(JWKS_URL).json()
def verify_alma_webhook(
request_body: bytes,
signature_header: str,
) -> bool:
try:
claims = jwt.decode(
signature_header,
jwks,
algorithms=["RS256"],
audience=YOUR_WEBHOOK_URL,
)
except Exception:
return False
expected_body_sha256 = hashlib.sha256(request_body).hexdigest()
return claims.get("body_sha256") == expected_body_sha256Pour chaque nouvelle tentative d’envoi, Alma génère une nouvelle signature JWT.
