API Webhooks

Les webhooks permettent à votre application de recevoir des notifications HTTP en temps réel lorsque des événements se produisent dans votre boutique Mercozy. Au lieu d'interroger l'API, enregistrez une URL et Mercozy enverra automatiquement les données de l'événement.

Démarrage rapide

Commencez en 3 étapes :

curl -X POST "https://api.mercozy.com/api/v1/external/webhooks" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My ERP Integration",
    "url": "https://your-app.com/webhooks/mercozy",
    "events": ["order.created", "order.cancelled", "payment.received"]
  }'

app.post('/webhooks/mercozy', (req, res) => {
  // 1. Verify signature (see below)
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Process the event
  const { type, data } = req.body;
  switch (type) {
    case 'order.created':
      syncOrderToERP(data);
      break;
    case 'payment.received':
      updateAccountingSystem(data);
      break;
  }

  // 3. Respond quickly with 200
  res.status(200).json({ received: true });
});

curl -X POST "https://api.mercozy.com/api/v1/external/webhooks/{id}/test" \
  -H "X-API-Key: mk_live_your_key_here"

Endpoints

Reference des Champs

Types d'Evenements Disponibles

Mercozy prend en charge 18 types d'événements webhook dans 6 catégories. Abonnez-vous uniquement aux événements dont vous avez besoin.

Payload du Webhook

Chaque livraison de webhook inclut le type d'evenement, l'horodatage et les donnees de la ressource concernee.

Données de l'événement de commande

{
  "id": "evt_clx1abc2def3",
  "type": "order.created",
  "timestamp": "2026-03-19T10:30:00Z",
  "data": {
    "id": "clx9order123",
    "orderNumber": "ORD-1042",
    "status": "PENDING",
    "total": 4999,
    "currency": "USD"
  }
}

Données de l'événement de paiement

{
  "id": "evt_clx2pay4ghi5",
  "type": "payment.received",
  "timestamp": "2026-03-19T10:35:00Z",
  "data": {
    "orderId": "clx9order123",
    "orderNumber": "ORD-1042",
    "amount": 4999,
    "currency": "USD",
    "paymentMethod": "CARD",
    "status": "CAPTURED"
  }
}

Données de l'événement de produit

{
  "id": "evt_clx3prod6jkl",
  "type": "product.created",
  "timestamp": "2026-03-19T11:00:00Z",
  "data": {
    "id": "clx9prod789",
    "name": "Organic Coffee Beans",
    "sku": "COF-001",
    "price": 1299,
    "status": "ACTIVE"
  }
}

Données de l'événement de livraison

{
  "id": "evt_clx4del7mno",
  "type": "delivery.completed",
  "timestamp": "2026-03-19T14:22:00Z",
  "data": {
    "orderId": "clx9order123",
    "orderNumber": "ORD-1042"
  }
}

En-têtes HTTP

Chaque requête webhook inclut les en-têtes suivants :

Verification de Signature

Chaque webhook inclut un en-tête X-Webhook-Signature contenant une signature HMAC-SHA256. Vérifiez toujours cette signature avant de traiter l'événement pour vous assurer que la requête provient de Mercozy.

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, timestamp, secret) {
  // Signature is computed over "timestamp.body"
  const message = timestamp + '.' + rawBody;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  const ts = req.headers['x-webhook-timestamp'];
  if (!verifyWebhook(req.body, sig, ts, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.status(200).json({ received: true });
});

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Signature is computed over "timestamp.body"
    message = (timestamp + '.').encode() + payload
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        message,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    sig = request.headers.get('X-Webhook-Signature')
    ts = request.headers.get('X-Webhook-Timestamp')
    if not verify_webhook(request.data, sig, ts, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    event = request.get_json()
    # Process event...
    return {'received': True}, 200

<?php
function verifyWebhook(string $payload, string $signature, string $timestamp, string $secret): bool {
    // Signature is computed over "timestamp.body"
    $message = $timestamp . '.' . $payload;
    $expected = 'sha256=' . hash_hmac('sha256', $message, $secret);
    return hash_equals($expected, $signature);
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
if (!verifyWebhook($payload, $signature, $timestamp, $webhookSecret)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($payload, true);
// Process event...
http_response_code(200);
echo json_encode(['received' => true]);

Politique de réessai

Si votre endpoint renvoie un code de statut non-2xx ou expire (10 secondes), Mercozy réessaiera la livraison avec un backoff exponentiel :

Après 3 tentatives échouées, la livraison est marquée comme échouée. Vous pouvez réessayer manuellement depuis le tableau de bord ou via l'API.

Bonnes pratiques

• Répondez en moins de 5 secondes — Renvoyez un statut 200 immédiatement et traitez l'événement de manière asynchrone. Le délai d'expiration de Mercozy est de 10 secondes.

• Vérifiez toujours les signatures — Vérifiez l'en-tête X-Webhook-Signature avant de traiter tout événement pour empêcher les requêtes usurpées.

• Gérez les doublons (idempotence) — Utilisez l'en-tête X-Webhook-ID pour dédupliquer les événements. Stockez les ID d'événements traités et ignorez ceux déjà gérés.

• Utilisez des endpoints HTTPS — Mercozy exige des URL HTTPS en production pour protéger les données webhook en transit.

• Journalisez et surveillez — Journalisez tous les webhooks entrants et surveillez les échecs. Utilisez l'API de journaux de livraison pour vérifier le statut.