--- title: "Configurer les webhooks par l'API" description: "Déclarez, remplacez et supprimez une URL de réception de webhook avec l'API Ciklik, et chargez le contrat OpenAPI dans vos outils." url: https://www.ciklik.academy/fr/webhooks/configurer-les-webhooks-par-lapi/ lang: fr lastUpdated: 2026-10-23 --- # Configurer les webhooks par l'API > Box et PrestaShop > > Cette page vaut pour les boutiques box comme pour les boutiques PrestaShop. > 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 le back-office à chaque changement. Pour le contrat des envois eux-mêmes (méthode, en-têtes, délais, tentatives), voir [Comprendre un envoi de webhook](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/). ## Authentification L’API vendors s’authentifie par jeton **Bearer**. Vous le créez vous-même : **Paramètres > Sites**, cliquez sur votre site, puis action **Créer un jeton API**. Donnez-lui un nom qui dit à quoi il sert, puis copiez le jeton affiché : il ne sera plus jamais affiché ensuite. Vos jetons sont listés dans la section **Jetons API** de la fiche du site. Chaque requête doit porter deux en-têtes : ``` Authorization: Bearer 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 à **200 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. Pour une autre intégration, créez un jeton dédié avec l’action **Créer un jeton API**. ## 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](https://www.ciklik.academy/fr/webhooks/) | **cURL :** ```bash curl -X POST https://app.ciklik.co/api/v3/webhooks \ -H "Authorization: Bearer " \ -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 :** ```json { "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 :** ```json { "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. Ajoutez-la dans le champ **Webhooks** de l’onglet **Avancé** de votre site. > 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 ``` ```bash curl -X DELETE https://app.ciklik.co/api/v3/webhooks \ -H "Authorization: Bearer " \ -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. Le même contenu s’affiche dans le champ **Webhooks** de l’onglet **Avancé** de votre site. Pour relire la configuration sans la modifier, appelez `GET /whoiam` : la réponse contient le même objet, dans `data.webhooks`. L’historique des envois, lui, se consulte dans le menu **Paramètres > Avancé > Webhooks** du back-office. ## 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 200 requêtes par minute | ## Le contrat OpenAPI Le fichier [`/openapi/ciklik-webhooks.yaml`](https://www.ciklik.academy/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](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/) [Bonnes pratiques et dépannage](https://www.ciklik.academy/fr/webhooks/bonnes-pratiques-et-depannage/) [Activer et tester un webhook](https://www.ciklik.academy/fr/webhooks/activer-et-tester-un-webhook/)