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://api.capturia.io/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://api.capturia.io/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://api.capturia.io/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 réunit deux sources, du plus récent au plus ancien :

• les événements enregistrés dans la file de livraison du compte, avec les données exactes qui ont été ou seront livrées ;
• complétés par les événements du journal d'activité que la file n'a pas enregistrés (aucune souscription ne les écoutait alors), mis en forme par le même constructeur.

Elle fonctionne donc même si aucune souscription webhook n'existe. Les événements émis hors du journal (lead_updated, note_created, task_created, sms_received, email_sent, call_ended…) n'apparaissent qu'une fois qu'une souscription les écoute : tant qu'aucune ne les écoute, ils ne sont enregistrés nulle part. 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 à sa source — lors d'une livraison réelle, id est l'identifiant unique de la livraison (X-Capturia-Delivery). Le champ data.system vaut toujours null dans un échantillon : il est résolu au moment de la livraison. 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://api.capturia.io/v1/webhook-events' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'