Webhooks

Les webhooks permettent à Cost+ de notifier votre serveur en temps réel chaque fois que le statut d'une commande change. Au lieu d'interroger l'API, vous fournissez une URL et Cost+ envoie une requête HTTP POST à cette URL à chaque mise à jour.

Fonctionnement des webhooks

Vous spécifiez un webhook_url lors de la création d'une commande, ou configurez une URL de webhook par défaut au niveau du projet.
Lorsque le statut de la commande change (ex. de new à completed), Cost+ envoie une requête POST à votre URL de webhook.
Votre serveur reçoit le webhook, puis appelle l'API Cost+ pour récupérer les détails complets de la commande.
Vous mettez à jour votre système en fonction du statut vérifié de la commande.

Ne faites jamais confiance au payload du webhook seul pour traiter une commande. Vérifiez toujours le statut de la commande en effectuant une requête GET /v1/orders/{id}/ après réception d'un webhook. Le webhook est un mécanisme de notification, pas une source de vérité.

Payload du webhook

Le corps du webhook est un objet JSON contenant le type d'événement et l'identifiant de la commande :

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Champ	Description
`event`	Le type d'événement. Actuellement `status_changed` pour les mises à jour de commande.
`order_id`	L'identifiant unique de la commande dont le statut a changé.
`project_id`	Le projet auquel appartient la commande.

Définir l'URL du webhook

Vous pouvez définir l'URL du webhook de deux manières :

Par commande

Incluez le champ webhook_url lors de la création d'une commande :

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Par défaut au niveau du projet

Configurez une URL de webhook par défaut dans votre tableau de bord Cost+ sous les paramètres du projet. Cette URL sera utilisée pour toutes les commandes qui ne spécifient pas leur propre webhook_url.

Même si vous avez un webhook par défaut au niveau du projet, vous pouvez le remplacer commande par commande en incluant webhook_url dans la requête de création de commande.

Logique de réessai

Si votre serveur ne répond pas avec un code de statut 2xx, Cost+ réessaie la livraison du webhook :

Nombre maximum de tentatives : 10
Intervalle entre les tentatives : 2 minutes
Délai d'expiration de la première tentative : 4 secondes
Délai d'expiration des tentatives suivantes : 10 secondes

Si les 10 tentatives échouent, le webhook est marqué comme échoué. Vous pouvez toujours récupérer le statut de la commande à tout moment en interrogeant l'API.

Assurez-vous que votre point d'accès webhook répond rapidement (dans les 4 secondes pour la première tentative). Effectuez tout traitement long de manière asynchrone après avoir renvoyé une réponse 200 OK.

Bonnes pratiques

Vérifiez toujours via l'API. À la réception d'un webhook, appelez GET /v1/orders/\{order_id\}/ pour confirmer le statut actuel avant d'entreprendre une action comme l'expédition de marchandises ou l'octroi d'un accès.
Renvoyez un 200 rapidement. Accusez réception du webhook avec une réponse 200 immédiatement et traitez la commande de manière asynchrone pour éviter les délais d'expiration.
Gérez les doublons. Votre point d'accès webhook peut recevoir le même événement plusieurs fois. Assurez-vous que votre logique de traitement est idempotente.
Utilisez HTTPS. Utilisez toujours une URL HTTPS pour votre point d'accès webhook afin de garantir la transmission sécurisée du payload.
Journalisez les payloads de webhook. Stockez les données de webhook entrantes à des fins de débogage et d'audit.

Points d'accès associés

Créer une commande — définir le webhook_url par commande
Mettre à jour une commande — mettre à jour l'URL de webhook d'une commande existante
Schémas d'événements webhook — format de payload pour OrderStatusChangedEvent et TransactionStatusChangedEvent

On this page