Configurer les webhooks par l'API

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 <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 à 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

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"}'

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

{
  "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.

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. 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 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.

Voir aussi

Comprendre un envoi de webhook

Bonnes pratiques et dépannage

Activer et tester un webhook