Passer au contenu principal
Les webhooks permettent à Orqex de pousser des événements vers votre serveur au fil de l’eau, sans interrogation en boucle. Cette page couvre le fonctionnement de la livraison ; pour la liste des événements de paiement et leur payload, voir webhooks de paiement.

​
Recevoir les événements

Deux façons de recevoir les événements :

Par paiement

Définissez un webhook_url à la création d’une intention ou d’un checkout. Les événements de ce paiement y sont livrés.

Endpoints projet

Enregistrez des endpoints de webhook dans le dashboard pour recevoir les événements de tout le projet.

​
Livraison

  • Orqex envoie un POST HTTP avec un corps JSON à votre URL.
  • Les en-têtes incluent X-Payment-Event (nom de l’événement) et X-Payment-Id (id du paiement).
  • Votre endpoint doit répondre 2xx rapidement ; déportez les traitements lents en asynchrone.

​
Fiabilité

  • Retries — les livraisons en échec sont réessayées automatiquement, jusqu’à 5 fois.
  • At-least-once — un même événement peut arriver plusieurs fois. Rendez le traitement idempotent en l’indexant sur payment.id + event.
  • L’ordre n’est pas garanti — fiez-vous au status courant du paiement, pas à l’ordre des événements.

​
Vérifier l’authenticité

Les endpoints de webhook du projet (enregistrés dans le dashboard) sont signés. Chaque endpoint a son propre secret de signature ; chaque livraison porte un en-tête x-orqex-signature contenant le HMAC-SHA256 du corps brut de la requête, calculé avec ce secret. Recalculez-le et comparez avant de faire confiance à la charge utile : 
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ORQEX_SIGNATURE'] ?? '';
$secret    = '...'; // le secret de signature de l'endpoint (whsec_...), affiché dans le dashboard

if (! hash_equals(hash_hmac('sha256', $payload, $secret), $signature)) {
    http_response_code(401);
    exit; // rejet : signature invalide
}
Les webhooks par paiement — ceux envoyés à un webhook_url défini sur un paiement ou un checkout — ne sont pas signés : une URL ad-hoc n’a pas de secret attaché. Pour ceux-ci, re-récupérez la ressource via l’API (ex. GET /payment/intents/{id}) et agissez sur cet état faisant autorité.

​
Inspecter les livraisons

Le dashboard conserve les journaux de webhooks sortants — chaque livraison, son statut et corps de réponse, et le nombre de tentatives — pour déboguer votre handler.