Webhooks
Deux sens : les événements Stripe vers COLVO pour la vérification et la réconciliation, et les alertes de COLVO vers Slack, l’e-mail ou votre propre webhook.
Entrants : Stripe → COLVO
Lorsque vous connectez un compte Stripe à un projet, COLVO vous fournit un endpoint de webhook pour cette connexion :
POST https://colvo.app/v1/webhooks/stripe/{connection_id}Ajoutez-le dans le tableau de bord Stripe avec le secret de signature affiché une seule fois dans COLVO. La signature des événements est vérifiée (stripe-signature), puis ils sont ajoutés à une boîte de réception durable et traités par le worker ; une signature absente ou invalide est refusée (400), de même que les corps de plus de 1 Mo (413). Abonnez-vous à refund.created, refund.updated, charge.refunded, customer.subscription.updated et customer.subscription.deleted (l’écran Connecter Stripe les liste). Les événements alimentent la vérification et la réconciliation ; COLVO n’agit jamais sur un événement non signé.
Paddle. Ajoutez dans Paddle une destination de notification avec l’URL affichée par COLVO (/v1/webhooks/paddle/{connection_id}) et les événements adjustment.created, adjustment.updated, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed. L’en-tête Paddle-Signature est vérifié avec la clé secrète de la destination (les horodatages de plus de 5 minutes sont refusés). adjustment.updated finalise un remboursement en attente de la revue de Paddle ; un remboursement rejeté ouvre un incident et libère le budget.
Chargebee. Chargebee protège les webhooks par une authentification HTTP basic plutôt que par une signature : ajoutez dans Chargebee un webhook avec l’URL (/v1/webhooks/chargebee/{connection_id}), le nom d’utilisateur colvo et le mot de passe que COLVO vous a affiché lors de la connexion, ainsi que les événements credit_note_created, payment_refunded, subscription_cancellation_scheduled, subscription_cancelled, subscription_scheduled_cancellation_removed, subscription_paused, subscription_pause_scheduled, subscription_resumed, subscription_scheduled_pause_removed, subscription_changed. Un mot de passe erroné ou absent est refusé (401). Les événements ne sont que des indices : la vérification relit toujours Chargebee.
Modifications effectuées en dehors de COLVO
Un remboursement ou une résiliation qu’aucune opération ni observation de COLVO n’explique — une ancienne clé encore présente dans l’agent, un remboursement manuel depuis le Dashboard — ouvre un incident UNEXPECTED_ACTION et déclenche vos alertes, après une seconde vérification une minute plus tard (notre propre écriture est peut-être encore en cours de validation). Par connexion : auto (par défaut : alerte seulement une fois que Guard a exécuté une action sur ce compte, de sorte que les connexions en simple observation restent silencieuses), alert ou ignore — PATCH /v1/projects/{id}/connections/{connection_id} avec { "out_of_band": "alert" }, ou le sélecteur de la page du projet.
Sortants : canaux d’alerte
GET / POST /v1/alert-channels, DELETE /v1/alert-channels/{id}, POST /v1/alert-channels/{id}/test. Par projet ; événements : run.failed, incident.opened, drift.detected, cap.threshold, approval.requested, approval.reminder, approval.expired.
{ "project_id": "…", "name": "ops", "events": ["run.failed", "incident.opened"],
"config": { "kind": "webhook", "url": "https://yourco.example/hooks/colvo", "secret": "optional shared secret" } }
// kinds: "slack" { webhook_url } · "email" { to: [...] } · "webhook" { url, secret? }Les envois de webhook sont en JSON, avec un en-tête HMAC-SHA256 X-Colvo-Signature lorsqu’un secret est défini, et sont retentés avec un backoff. Slack utilise une URL d’incoming webhook ; l’e-mail passe par Resend avec le modèle aux couleurs de COLVO.