Webhooks paiement externe — HelloAsso & PayZen

Kohinos accepte les paiements en euros via deux gateways : HelloAsso (cotisations MLCC, dons, adhésion) et PayZen (rechargement eMLc par carte bancaire, cotisation SSA). Dans les deux cas, la confirmation de paiement arrive de façon asynchrone par un webhook serveur-à-serveur. Tant que le webhook n'a pas été reçu, validé et persisté, aucune monnaie locale n'est créditée — l'opération côté Kohinos est en attente. C'est ce contrat de fiabilité que couvre cette page : signature, idempotence, atomicité, ordre des effets.

Flux HelloAsso (Order/Payment)

sequenceDiagram
    autonumber
    participant Adh as Adhérent
    participant HA as HelloAsso
    participant Ctl as HelloAssoCallbackController
    participant Auth as HelloAssoWebhookAuthenticator
    participant Pay as HelloAssoPaymentService
    participant DB
    participant Mail as Mailer (subscriber)
    Adh->>HA: Paiement formulaire (Checkout / Membership)
    HA->>Ctl: POST /helloasso/callback/{webhookToken}
    Ctl->>Auth: isAuthorised(webhookToken)
    Note over Auth: hash_equals(secret URL)
    Auth-->>Ctl: true
    Ctl->>Pay: getOrCreateHelloAsso(helloassoid, data)
    Note over Pay: findOneBy(['helloassoid'=>…])
    alt déjà connu (rejeu)
        Pay-->>Ctl: HelloAsso existant
        Ctl-->>HA: 200 OK (no-op)
    else première occurrence
        Pay->>DB: wrapInTransaction Flux + Operation
        Pay->>DB: setHelloassoid + persist
        Ctl->>Mail: dispatch (event subscriber)
        Ctl-->>HA: 200 OK
    end
    

Flux PayZen (IPN via Payum)

sequenceDiagram
    autonumber
    participant Adh as Adhérent
    participant PZ as PayZen
    participant Ctl as FluxController::doneAction
    participant Pum as Payum
    participant Gw as PayzenGateway
    participant DB
    Adh->>PZ: Paiement CB sur formulaire hébergé
    par retour navigateur
        PZ-->>Adh: redirect /payment/done/?payum_token=…
    and IPN serveur-à-serveur
        PZ->>Ctl: POST /payment/done/ (kr-hash + payum_token)
    end
    Ctl->>Pum: httpRequestVerifier->verify(request)
    Note over Pum: vérifie payum_token (one-shot)
    Pum-->>Ctl: token
    Ctl->>Gw: execute(new Notify(token))
    Note over Gw: vérifie kr-hash (HMAC-SHA256)
    Gw->>DB: maj Payment.status
    Ctl->>Gw: execute(new GetHumanStatus(token))
    alt STATUS_CAPTURED / AUTHORIZED
        Ctl->>Pum: httpRequestVerifier->invalidate(token)
        Ctl->>DB: deserialize Flux + persist (wrapInTransaction)
    else canceled / failed
        Ctl->>Pum: invalidate(token)
    end
    Ctl-->>PZ: 200 OK
    

Comparatif HelloAsso vs PayZen

Règles dures (à ne pas négocier)

Anti-patterns observés

Tests de webhooks

Payload HelloAsso de référence

{
  "eventType": "Order",
  "data": {
    "id": 123456789,
    "formSlug": "adhesion-2026",
    "formType": "Membership",
    "payer": {
      "email": "alice@example.org",
      "firstName": "Alice",
      "lastName": "Durand"
    },
    "amount": { "total": 2000, "vat": 0 },
    "items": [
      { "id": 987, "type": "Membership", "amount": 2000 }
    ]
  }
}

Rejouer en local (instance dev, token webhook configuré dans .env.local) :

WEBHOOK_TOKEN="${HELLOASSO_WEBHOOK_TOKEN}"

curl -i -X POST "http://kohinos.local/helloasso/callback/${WEBHOOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data @tests/fixtures/helloasso/order_membership.json

Tester l'idempotence (rejeu identique)

# 1er envoi → 200, Flux créé
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST "http://kohinos.local/helloasso/callback/${WEBHOOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data @tests/fixtures/helloasso/order_membership.json
# → 200

# 2e envoi (même helloassoid) → 200, AUCUN nouveau Flux
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST "http://kohinos.local/helloasso/callback/${WEBHOOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data @tests/fixtures/helloasso/order_membership.json
# → 200

# Vérification SQL : un seul flux pour cet order
mysql -e "SELECT COUNT(*) FROM helloasso WHERE helloassoid = 123456789;"
# → 1

Payload PayZen de référence (IPN)

kr-answer-type=V4/Payment&
kr-answer={"orderDetails":{"orderId":"abc123"},"transactions":[{...,"status":"PAID"}]}&
kr-hash=9e1c2f4a7b...&
kr-hash-algorithm=sha256_hmac&
kr-hash-key=hmacsha256

Rejouer un IPN PayZen (token Payum encore valide) :

curl -i -X POST "http://kohinos.local/payment/done/?payum_token=${TOKEN}" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "kr-answer-type=V4/Payment" \
  --data-urlencode "kr-answer=@tests/fixtures/payzen/payment_paid.json" \
  --data-urlencode "kr-hash=${VALID_HMAC}" \
  --data-urlencode "kr-hash-algorithm=sha256_hmac"

Observabilité

Channels Monolog

Métriques à surveiller

• Taux de succès : ratio réponses 2xx / total webhooks reçus. Cible > 99,5 % sur 7 jours glissants.
• Latence p95 : temps de traitement du webhook. Cible < 1 s, seuil d'alerte > 3 s (HelloAsso retentera à 5 s).
• Taux de retries : nombre de webhooks rejoués avec un helloassoid déjà connu. Une hausse peut signaler une latence trop élevée côté Kohinos.
• Rejets d'auth : compteur d'événements warning token mismatch — une hausse soudaine = scan en cours (mettre en quarantaine).
• Divergence Order/Flux : requête nocturne comparant le nombre d'HelloAsso aux Flux rattachés. Toute différence non expliquée doit être investiguée.

Requête d'audit type

-- HelloAsso orders reçus mais sans Flux associé (réconciliation)
SELECT h.helloassoid, h.created_at, h.email
FROM helloasso h
LEFT JOIN flux f ON f.helloasso_id = h.id
WHERE f.id IS NULL
  AND h.created_at > NOW() - INTERVAL 7 DAY
ORDER BY h.created_at DESC;

Pour aller plus loin