Guide des Webhooks

Présentation

Les webhooks permettent à votre application de recevoir des notifications HTTP POST en temps réel lorsque des événements se produisent dans Kataio. Au lieu d'interroger l'API, votre serveur reçoit des notifications push dès que les données changent.

Configuration des Webhooks

1. Allez dans Paramètres → Intégrations → Webhooks
2. Cliquez sur Ajouter un Webhook
3. Entrez l'URL de votre endpoint (HTTPS obligatoire)
4. Sélectionnez les événements auxquels vous souhaitez vous abonner
5. Copiez le secret de signature pour la vérification

Événements disponibles

Payload du Webhook

Chaque livraison de webhook envoie un payload JSON comme celui-ci :

{
  "id": "evt_abc123",
  "event": "product.updated",
  "timestamp": "2026-03-15T14:30:00Z",
  "data": {
    "id": "prod_xyz789",
    "name": "Casque sans fil Premium",
    "sku": "WH-PRO-001",
    "updatedFields": ["price", "description"]
  }
}

Les événements de statut de commande (order.status_changed et les événements granulaires order.shipped / order.delivered / order.cancelled / order.returned) partagent le même format data. À l'expédition, les champs de suivi sont renseignés :

{
  "id": "evt_def456",
  "event": "order.shipped",
  "timestamp": "2026-06-13T16:40:00Z",
  "data": {
    "id": "a1b2c3d4-...",
    "externalId": "CNB-M5Q0YE",
    "previousStatus": "PROCESSING",
    "status": "SHIPPED",
    "customerId": "d4e5f6a7-...",
    "customerEmail": "client@example.com",
    "totalAmount": "534.00",
    "currency": "EUR",
    "trackingCarrier": "Colissimo",
    "trackingNumber": "6A12345678901",
    "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6A12345678901",
    "updatedAt": "2026-06-13T16:40:00Z"
  }
}

trackingCarrier, trackingNumber et trackingUrl sont nuls tant que la commande n'est pas marquée expédiée avec un suivi. order.shipped est émis en même temps que order.status_changed.

Vérification de la signature

Chaque requête webhook inclut un en-tête X-Webhook-Signature contenant une signature HMAC-SHA256. Vérifiez toujours cette signature pour vous assurer que la requête provient d'Kataio.

Node.js

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

PHP

function verifyWebhookSignature(
    string $payload,
    string $signature,
    string $secret
): bool {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Python

import hmac
import hashlib

def verify_webhook_signature(
    payload: bytes,
    signature: str,
    secret: str
) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Politique de nouvelle tentative

Si votre endpoint ne répond pas avec un code de statut 2xx dans les 10 secondes, Kataio retentera la livraison :

Après 5 tentatives échouées, le webhook est marqué comme échoué. Vous pouvez consulter et retenter manuellement les livraisons échouées depuis votre tableau de bord.

Bonnes pratiques

• Répondez rapidement : Renvoyez un 200 OK immédiatement, puis traitez l'événement de manière asynchrone
• Gérez les doublons : Utilisez le champ id pour dédupliquer — le même événement peut être livré plusieurs fois
• Vérifiez les signatures : Validez toujours l'en-tête X-Webhook-Signature avant de traiter
• Utilisez une file d'attente : Poussez les payloads webhook vers une file de messages pour un traitement fiable
• Surveillez les échecs : Vérifiez régulièrement vos journaux de livraison webhook dans le tableau de bord
• Testez localement : Utilisez des outils comme ngrok pour tester les webhooks pendant le développement

Webhooks entrants des plateformes

Le sens inverse : les places de marché et plateformes e-commerce appellent Kataio quand une commande ou un produit change de leur côté. Ces endpoints sont publics (pas de clé API) — chaque requête est authentifiée par la signature propre à la plateforme, vérifiée avec le secret enregistré sur le canal. Vous n'en avez besoin que si vous enregistrez l'URL vous-même dans le back-office de la plateforme — Kataio enregistre lui-même les webhooks Shopify, WooCommerce et eBay quand le test de connexion du canal réussit (POST /channels/{channelId}/sync/test).

POST https://app.kataio.com/api/v1/webhooks/platform/{channelId}/{platform}

TikTok Shop fonctionne avec votre propre application : enregistrez …/{channelId}/tiktok-shop dans votre application Partner Center. Un en-tête absent, un corps brut illisible ou une signature différente répond 401. Les livraisons sont dédupliquées sur tts_notification_id pendant 24 heures. Sujets traités : ORDER_STATUS_CHANGE (met en file une récupération des commandes), PRODUCT_STATUS_CHANGE, SELLER_DEAUTHORIZATION (le canal passe en needs_reauth) et UPCOMING_AUTHORIZATION_EXPIRATION (le canal passe en expiring).

Réponses

• 201 { "received": true, "action": "stock_propagation_queued" } — traité (action peut aussi valoir pull_orders_queued, needs_reauth, expiring…)
• 201 { "received": true, "duplicate": true } — même tts_notification_id vu dans les 24 dernières heures (TikTok Shop)
• 201 { "received": true, "ignored": true } ou { "received": true, "action": "ignored", "reason": "…" } — type d'événement non traité
• 400 — signature invalide (WooCommerce, Shopify, PrestaShop, eBay) ou canal inactif ; 401 — signature TikTok Shop invalide
• 404 — canal inconnu, ou canal qui n'est pas TikTok Shop sur /tiktok-shop