Webhooks : documentation CheckoutOS

Les webhooks permettent de recevoir des notifications en temps réel lorsque des événements se produisent dans CheckoutOS. Au lieu d’interroger périodiquement l’API, les webhooks envoient les données à votre serveur au moment des événements.

Événements disponibles

Événements webhook

upsell.accepted — Le client a accepté une offre de vente incitative
upsell.declined — Le client a refusé une offre de vente incitative
bundle.purchased — Un lot a été acheté
experiment.concluded — Le test A/B a atteint la significativité
order.edited — Le client a modifié sa commande
order.cancelled — Le client a annulé sa commande
subscription.created — La vente incitative d’abonnement a été convertie

Créer des webhooks

Accéder aux webhooks

Accédez à CheckoutOS → Settings → Webhooks.

Ajouter un point de terminaison

Cliquez sur "Add Webhook Endpoint".

Saisir l’URL

Saisissez l’URL HTTPS qui recevra les événements.

Sélectionner les événements

Choisissez les événements auxquels vous abonner.

Enregistrer

Enregistrez et notez le secret de signature.

Créer un webhook via l’API

curl -X POST "https://api.chargezen.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/checkoutos",
    "events": ["upsell.accepted", "bundle.purchased"],
    "enabled": true
  }'

# Response
{
  "id": "wh_123",
  "url": "https://yourserver.com/webhooks/checkoutos",
  "events": ["upsell.accepted", "bundle.purchased"],
  "signing_secret": "whsec_abc123...",
  "enabled": true
}

Charge utile du webhook

upsell.accepted

Événement de vente incitative acceptée

{
  "id": "evt_123456",
  "type": "upsell.accepted",
  "created_at": "2025-01-16T14:30:00Z",
  "data": {
    "upsell_id": "upsell_abc",
    "upsell_name": "Premium Add-On",
    "order_id": "order_789",
    "shopify_order_id": "5678901234",
    "customer_id": "cust_456",
    "product": {
      "id": "prod_xyz",
      "title": "Premium Widget",
      "variant_id": "var_123",
      "price": 29.99
    },
    "discount": {
      "type": "percentage",
      "value": 15,
      "amount": 4.50
    },
    "final_price": 25.49
  }
}

bundle.purchased

Événement d’achat de lot

{
  "id": "evt_234567",
  "type": "bundle.purchased",
  "created_at": "2025-01-16T15:00:00Z",
  "data": {
    "bundle_id": "bundle_def",
    "bundle_name": "Skincare Starter Kit",
    "bundle_type": "fixed",
    "order_id": "order_890",
    "products": [
      { "id": "prod_a", "title": "Cleanser", "quantity": 1 },
      { "id": "prod_b", "title": "Toner", "quantity": 1 },
      { "id": "prod_c", "title": "Moisturizer", "quantity": 1 }
    ],
    "original_price": 89.97,
    "bundle_price": 71.98,
    "savings": 17.99
  }
}

order.edited

Événement de modification de commande

{
  "id": "evt_345678",
  "type": "order.edited",
  "created_at": "2025-01-16T15:30:00Z",
  "data": {
    "order_id": "order_901",
    "shopify_order_id": "6789012345",
    "edit_type": "add_items",
    "changes": {
      "items_added": [
        { "product_id": "prod_new", "quantity": 1, "price": 19.99 }
      ],
      "items_removed": [],
      "quantity_changes": []
    },
    "amount_changed": 19.99,
    "new_total": 109.98
  }
}

Vérifier les webhooks

Tous les webhooks incluent un en-tête de signature pour vérification :

Vérification Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// Express middleware
app.post('/webhooks/checkoutos', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-checkoutos-signature'];

  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Handle event...

  res.status(200).send('OK');
});

Vérification Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f'sha256={expected}',
        signature
    )

# Flask example
@app.route('/webhooks/checkoutos', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-CheckoutOS-Signature')

    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.get_json()
    # Handle event...

    return 'OK', 200

Toujours vérifier

Vérifiez toujours la signature des webhooks avant de les traiter. Cela empêche les attaquants d’envoyer de faux événements à votre point de terminaison.

Politique de nouvelle tentative

Les envois de webhook échoués sont réessayés avec un délai croissant exponentiellement :

Calendrier des nouvelles tentatives

{
  "retry_policy": {
    "max_attempts": 5,
    "schedule": [
      { "attempt": 1, "delay": "immediately" },
      { "attempt": 2, "delay": "5 minutes" },
      { "attempt": 3, "delay": "30 minutes" },
      { "attempt": 4, "delay": "2 hours" },
      { "attempt": 5, "delay": "24 hours" }
    ],
    "success_codes": [200, 201, 202, 204],
    "timeout": "30 seconds"
  }
}

Tester les webhooks

Testez votre point de terminaison webhook avant la mise en service :

Envoyer un événement de test

curl -X POST "https://api.chargezen.com/v1/webhooks/wh_123/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "upsell.accepted"
  }'

Journaux des webhooks

Consultez l’historique des envois de webhook dans le tableau de bord ou via l’API :

Récupérer les journaux des webhooks

curl -X GET "https://api.chargezen.com/v1/webhooks/wh_123/logs" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "log_123",
      "event_id": "evt_456",
      "event_type": "upsell.accepted",
      "status": "delivered",
      "response_code": 200,
      "duration_ms": 245,
      "created_at": "2025-01-16T14:30:00Z"
    }
  ]
}

Bonnes pratiques

Conseils sur les webhooks

Répondez rapidement — Renvoyez 200 sous 30 secondes
Traitez de manière asynchrone — Mettez les événements en file pour un traitement en arrière-plan
Gérez les doublons — Les événements peuvent être envoyés plusieurs fois
Vérifiez les signatures — Validez toujours avant le traitement
Surveillez les échecs — Configurez des alertes pour les envois échoués

Sujets associés

Authentification

Gestion des clés API

Points de terminaison API

Référence complète des points de terminaison