Webhooks

Lister les souscriptions webhooks

Retourne la liste des souscriptions webhooks créées par la clé API appelante. Les souscriptions créées par une autre clé du même client ne sont PAS visibles ici (filtre client_id AND api_key_id).

Pas de pagination cursor

Le maximum de 10 souscriptions par client tient toujours dans une seule page. La réponse retourne pagination.next_cursor=null et has_more=false.

Secret jamais retourné

Le secret HMAC utilisé pour signer les payloads sortants n'est retourné qu'à la création (POST /v1/webhooks). Il n'est pas relu ici — pour le faire tourner, supprimer la souscription et en créer une nouvelle.

curl -X GET 'https://app.capturia.io/api/v1/webhooks' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

Créer une souscription webhook

Enregistre une nouvelle souscription. Capturia émettra un POST JSON signé HMAC à url chaque fois qu'un événement souscrit survient.

URL HTTPS obligatoire

L'URL doit utiliser le schéma https:// — http:// est rejeté pour éviter la fuite des payloads en clair.

Limite de 10 souscriptions par client

Au-delà de 10 souscriptions actives sur un même client (toutes clés confondues), retourne 429 subscription_limit_reached. Supprimer une souscription existante avant d'en créer une nouvelle.

Secret HMAC retourné UNE seule fois

La réponse 201 inclut secret en clair (64 caractères hex, 256 bits d'entropie). Le client DOIT le stocker immédiatement — il sert à vérifier la signature des payloads sortants (X-Capturia-Signature) et n'est plus jamais retourné par l'API. Le secret est chiffré en base après cette réponse.

Scope de la clé créatrice

La souscription appartient à la fois au client ET à la clé API qui l'a créée. Les endpoints GET /v1/webhooks et DELETE /v1/webhooks/{id} ne voient que les souscriptions de la clé courante — une souscription créée par une autre clé du même client n'est ni listée ni supprimable via l'API.

curl -X POST 'https://app.capturia.io/api/v1/webhooks' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://hooks.example.com/capturia",
  "events": [
    "lead_created",
    "payment_received"
  ]
}'

Supprimer une souscription webhook

Supprime définitivement une souscription webhook. La souscription doit appartenir à la fois au client appelant ET à la clé API appelante (filtre client_id AND api_key_id) — sinon 404 not_found.

Pas de soft delete

La suppression est immédiate et irréversible — pour réactiver le flux d'événements, créer une nouvelle souscription via POST /v1/webhooks (un nouveau secret sera émis).

curl -X DELETE 'https://app.capturia.io/api/v1/webhooks/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

Lister les derniers événements métier livrables (échantillons)

Retourne les derniers événements métier du compte, dans exactement la forme du payload livré par une souscription webhook — le même constructeur de payload sert la livraison réelle et cette liste.

À quoi ça sert

• performList des apps Zapier/Make : quand un utilisateur teste un trigger, l'app affiche de vrais échantillons récents, garantis identiques à ce qu'une livraison réelle enverra.
• Debug d'intégration : inspecter ce qui serait livré sans attendre un nouvel événement.

La liste fonctionne même si aucune souscription webhook n'existe : elle est bâtie depuis le journal d'activité du compte, filtré au catalogue des événements livrables. Les types d'événements internes (audit) n'apparaissent jamais, et les clés sensibles du champ changes sont expurgées comme à la livraison.

Différence avec une livraison réelle

Le champ id de chaque item est l'identifiant de l'événement dans le journal d'activité — lors d'une livraison réelle, id est l'identifiant unique de la livraison (X-Capturia-Delivery). La forme et tous les autres champs sont identiques.

Pas de pagination cursor

C'est un flux d'échantillons récents, plafonné à 25 items (limit, défaut 10). La réponse retourne pagination.next_cursor=null et has_more=false.

curl -X GET 'https://app.capturia.io/api/v1/webhook-events' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'