Bonnes pratiques et dépannage

Répondre correctement

Répondez par un code 2xx le plus vite possible, mettez le contenu de l’envoi de côté, et traitez-le ensuite de façon asynchrone. Trois raisons imposent cet ordre, la première étant la plus importante.

1. Le doublon est garanti si vous êtes trop lent. Ciklik attend votre réponse pendant 30 secondes. Si votre traitement dépasse ce délai avant de répondre, Ciklik considère l’envoi comme perdu et le rejoue jusqu’à quatre fois, alors que votre serveur l’a bien reçu et l’a peut-être déjà traité quatre fois. Répondre d’abord, traiter ensuite, est la seule parade à ce doublon.
2. Ciklik n’analyse pas le code que vous renvoyez. Un 500 de votre côté ne déclenche aucun nouvel envoi : la perte est sèche et définitive.
3. Ne répondez jamais par une redirection. Une redirection efface le contenu de l’envoi (voir plus bas) et laisse une trace trompeuse.

Ce qui est retenté, ce qui ne l’est pas

Situation	Comportement
URL de réception injoignable, DNS cassé, connexion refusée, délai de connexion dépassé, certificat invalide	5 tentatives au total : 30 secondes d’attente entre les trois premières, puis les deux dernières enchaînées sans attente
Réponse 4xx ou 5xx	Aucune nouvelle tentative : l’envoi est considéré comme délivré
Trop de redirections suivies	Tentatives immédiates, puis abandon

Un 500 de votre côté est une perte sèche

Ciklik ne relit jamais le code de réponse. Une erreur applicative chez vous n’est pas rejouée : traitez donc le contenu de façon défensive, dans une file que vous contrôlez, une fois le 2xx envoyé.

Absorber les doublons et le désordre

• Traitez par identifiant d’objet (id ou uuid), jamais par ordre d’arrivée. L’ordre n’est pas garanti : les envois partent avec des délais différents et plusieurs envois peuvent être traités en parallèle, un envoi updated_* peut donc arriver avant le created_* du même objet.
• Comparez l’état reçu à votre état local avant d’agir, plutôt que d’appliquer un écart à l’aveugle. Le contenu de l’envoi reflète l’état de l’objet au moment où Ciklik l’a envoyé, pas au moment de l’événement : seul changed reflète l’instant exact de l’événement.
• Rendez votre traitement rejouable. Le même envoi reçu deux fois doit produire le même résultat que reçu une fois : c’est la seule protection réelle contre les doublons, qui sont fréquents (cascades, enregistrements successifs, renvois sur lenteur).
• Ignorez un envoi dont l’horodatage de l’objet est plus ancien que celui déjà enregistré chez vous. C’est ce qui vous protège quand deux envois arrivent dans le désordre.

Sécuriser votre URL de réception

Il n’y a ni signature ni secret partagé dans un envoi Ciklik : aucun en-tête d’authentification, rien à vérifier dans le corps. Votre URL de réception est donc le seul secret du dispositif.

• Utilisez HTTPS : sans lui, les données de vos clients circulent en clair.
• Choisissez un chemin long et non devinable, jamais /webhook ou /hook.
• Ne publiez jamais cette URL, ne la mettez pas dans un dépôt public ni dans un fichier de configuration partagé.
• Ciklik ne publie pas d’adresse IP fixe pour ses envois : ne filtrez pas par adresse IP, c’est le chemin non devinable qui protège votre URL.
• Votre certificat doit être valide et émis par une autorité reconnue.

Un certificat invalide ne laisse aucune trace

Un certificat auto-signé ou expiré fait échouer l’envoi sans qu’aucune ligne ne soit écrite dans le journal que l’équipe Ciklik peut vous communiquer : voir plus bas.

Deux règles supplémentaires, indépendantes du protocole :

• Vérifiez une information critique par un appel à l’API Ciklik avant d’agir sur de l’argent ou sur l’expédition d’un colis. Le contenu de l’envoi n’est pas un ordre, c’est une notification.
• N’exploitez et ne stockez que les champs documentés. Le contenu comprend des données personnelles de vos clients et des champs techniques internes qui peuvent changer sans préavis. Traitez ce contenu comme une donnée personnelle au sens du RGPD.

Diagnostiquer

1. Rejouez un envoi de test vers votre URL de réception, depuis l’extérieur, avec un exemple de contenu. Enregistrez d’abord l’exemple de la page Événements : abonnements dans un fichier exemple-created_subscription.json.

   curl -X POST https://votre-url-de-reception/chemin \
     -H "Content-Type: application/json" \
     -d @exemple-created_subscription.json

2. Vérifiez l’absence de redirection.

   curl -sS -o /dev/null -w "%{http_code} %{redirect_url}\n" https://votre-url-de-reception/chemin

   Un code 301, 302 ou 303, ou une valeur après le code, signale une redirection : le contenu de Ciklik s’y perd.

3. Vérifiez le certificat, sans jamais utiliser l’option --insecure.

   curl -sSI https://votre-url-de-reception/chemin

   Si cette commande échoue, votre certificat n’est pas valide.

4. Vérifiez que la clé d’événement activée correspond bien à l’action que vous venez de faire : un test sur updated_subscription ne produit rien si vous venez de créer une commande.

5. Attendez 60 secondes après tout changement de configuration : une nouvelle URL de réception met jusqu’à une minute à être prise en compte.

6. Demandez à l’équipe Ciklik la trace de l’envoi correspondant à votre test.

Lire la trace conservée par l’équipe

C’est l’étape décisive : l’équipe Ciklik conserve, pour chaque envoi réellement parti, l’URL appelée, le contenu envoyé, le code et le corps de la réponse reçue, et l’heure. Son état se lit ainsi :

• Aucune trace pour la période : la connexion n’a jamais abouti. DNS, connexion refusée, délai d’établissement dépassé ou certificat invalide en sont les causes possibles. Rien n’est parti, et dans ce cas précis aucune ligne n’est jamais écrite : l’absence de trace n’est pas un défaut de journalisation, c’est l’information elle-même.
• Trace avec un code 200 et un corps HTML : votre URL a très probablement redirigé. Le contenu a été perdu en route, et le 200 enregistré est celui de la page d’arrivée, pas une preuve de traitement.
• Trace avec un code 4xx ou 5xx : l’envoi vous est bien parvenu, votre serveur l’a refusé, et il ne sera jamais rejoué.
• L’heure enregistrée est celle de la réponse, pas celle du déclenchement. Un écart de plusieurs secondes avec l’action d’origine est normal.

Ces traces sont conservées 20 jours.

FAQ

Puis-je déclarer plusieurs URL pour un même événement ?

Non. Une seule URL par clé d’événement : la nouvelle déclaration remplace toujours l’ancienne, sans avertissement.

Comment savoir de quel événement il s’agit à la réception ?

Le nom de l’événement n’est pas dans le contenu de l’envoi. Vous le savez par l’URL que vous avez enregistrée pour cette clé d’événement.

Pourquoi est-ce que je reçois plusieurs fois le même événement ?

Trois causes courantes : des cascades qui enregistrent plusieurs fois le même objet dans un même flux, des enregistrements successifs légitimes, ou une réponse trop lente de votre part qui déclenche un renvoi (voir « Répondre correctement »).

Pourquoi ne reçois-je rien quand une expédition part réellement ?

Le passage au statut expédié n’est notifié par updated_shippingbox que lorsqu’il est posé par l’API vendors ou par l’import de numéros de suivi de l’équipe Ciklik. Il n’est jamais notifié quand il provient des connecteurs logistiques Wonderweb ou Effitrace : sur ces canaux, suivez plutôt les mises à jour de l’expédition qui précèdent l’envoi physique, ou interrogez l’API.

Puis-je demander à rejouer un envoi manqué ?

Non, il n’existe pas de renvoi à la demande. Passez par l’API Ciklik pour récupérer l’état courant de l’objet concerné.

Dois-je vérifier une signature sur chaque envoi ?

Il n’y en a pas : aucun envoi Ciklik n’est signé. C’est votre URL de réception, non devinable, qui protège le dispositif.

Combien de temps gardez-vous la trace d’un envoi ?

20 jours. Au-delà, la trace n’existe plus : demandez-la dès le début d’un diagnostic.