Configurer les webhooks par l'API

Pour les développeurs

Cette page décrit l’API qui permet de déclarer, remplacer et supprimer une URL de réception par programmation, sans passer par une demande à l’équipe Ciklik à chaque changement. Pour le contrat des envois eux-mêmes (méthode, en-têtes, délais, tentatives), voir Comprendre un envoi de webhook.

Authentification

L’API vendors s’authentifie par jeton Bearer, fourni par l’équipe Ciklik. Chaque requête doit porter deux en-têtes :

Authorization: Bearer <jeton>
Accept: application/json

L’en-tête Accept: application/json est obligatoire. Sans lui, le serveur ne reconnaît pas la requête comme un appel API : une erreur d’authentification ou de validation revient alors sous la forme d’une redirection HTML, et non d’une réponse JSON que votre code peut interpréter.

L’API est limitée à 100 requêtes par minute et par adresse IP, et non par jeton : si plusieurs intégrations sortent par la même adresse réseau (un même serveur, un même proxy sortant), elles se partagent ce quota. Au-delà, la réponse est un code 429 dont le corps n’est pas du JSON.

Sur un site PrestaShop, un jeton est créé automatiquement lors de la configuration du module de paiement. Si vous intégrez sans disposer d’un jeton, demandez-le à l’équipe Ciklik.

Déclarer une URL de réception

POST https://app.ciklik.co/api/v3/webhooks

Champ	Type	Obligatoire	Description
hook_url	string (URL)	Oui	URL de réception, syntaxiquement valide
event_type	string	Oui	Clé de l’événement, voir le catalogue des événements

cURL

curl -X POST https://app.ciklik.co/api/v3/webhooks \
  -H "Authorization: Bearer <jeton>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"hook_url": "https://boutique.example.com/webhooks/ciklik", "event_type": "updated_subscription"}'

Réponse 200

200 OK

{
  "data": {
    "id": 1,
    "host": "boutique.example.com",
    "name": "Boutique Exemple",
    "paymentMethods": ["stripe"],
    "webhooks": {
      "updated_subscription": "https://boutique.example.com/webhooks/ciklik"
    },
    "metadata": null
  }
}

Erreur 422

422 Unprocessable Entity

{
  "message": "The selected event type is invalid.",
  "errors": {
    "event_type": [
      "The selected event type is invalid."
    ]
  }
}

Trois précisions avant d’intégrer :

• un second appel sur le même event_type remplace l’URL précédente, sans avertissement ;
• la nouvelle URL est prise en compte au bout d’une minute au plus ;
• updated_change_choices n’est pas accepté par cet endpoint : cette clé n’existe pas dans la liste validée et renvoie un 422. Elle ne peut être activée que par l’équipe Ciklik.

La validation ne teste pas votre URL

La vérification porte uniquement sur la syntaxe de hook_url. Une URL en http:// est acceptée, une URL inaccessible aussi : aucun appel de test n’est fait au moment de la déclaration. Utilisez HTTPS, et vérifiez vous-même, de votre côté, que l’adresse répond.

Supprimer une URL de réception

DELETE https://app.ciklik.co/api/v3/webhooks

curl -X DELETE https://app.ciklik.co/api/v3/webhooks \
  -H "Authorization: Bearer <jeton>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "updated_subscription"}'

La réponse a la même forme que pour une déclaration : l’objet webhooks complet, sans la clé que vous venez de retirer.

Connaître les URL déclarées

La réponse de POST et de DELETE porte déjà l’objet webhooks complet : c’est le moyen fiable de connaître l’état de votre configuration après chaque appel. Il existe aussi un endpoint GET /webhooks, mais son usage est déconseillé et son résultat n’est pas garanti.

Codes de réponse

Code	Sens	Que faire
200	Requête traitée	-
401	Authentification requise : jeton absent ou invalide	Vérifiez l’en-tête Authorization
422	Paramètre invalide ou clé d’événement inconnue	Vérifiez hook_url et event_type
429	Quota par adresse IP dépassé (corps en texte brut, pas de JSON)	Espacez vos appels, restez sous 100 requêtes par minute

Le contrat OpenAPI

Le fichier /openapi/ciklik-webhooks.yaml décrit formellement l’ensemble du système : les 18 clés d’événement sous webhooks, les trois opérations de configuration décrites sur cette page, tous les schémas d’objets utilisés dans les charges utiles, et un exemple réel complet par clé d’événement.

Trois usages concrets :

• le charger dans un client d’API (Postman, Insomnia, Bruno) pour disposer immédiatement des requêtes ;
• générer des types (TypeScript, PHP) à partir du contrat plutôt que de les écrire à la main ;
• le donner à un assistant de code pour qu’il écrive votre endpoint de réception directement à partir des schémas et des exemples.

Bonne pratique

Partez du fichier OpenAPI plutôt que de recopier les tableaux de cette rubrique à la main : c’est la version qui reste synchronisée avec le code.

Voir aussi : Comprendre un envoi de webhook pour le contrat complet des envois, et Bonnes pratiques et dépannage pour sécuriser votre URL de réception.