Webhooks
Zwei Richtungen: Stripe-Events an COLVO für Verifizierung und Abgleich sowie COLVO-Alerts an Slack, E-Mail oder Ihren eigenen Webhook.
Eingehend: Stripe → COLVO
Wenn Sie ein Stripe-Konto mit einem Projekt verbinden, stellt COLVO Ihnen einen Webhook-Endpunkt für diese Verbindung bereit:
POST https://colvo.app/v1/webhooks/stripe/{connection_id}Tragen Sie ihn im Stripe-Dashboard ein, zusammen mit dem Signatur-Secret, das COLVO einmalig anzeigt. Die Signatur der Events wird geprüft (stripe-signature), die Events werden in eine dauerhafte Inbox geschrieben und vom Worker verarbeitet; eine fehlende oder ungültige Signatur wird abgelehnt (400), ebenso Bodys über 1 MB (413). Abonnieren Sie refund.created, refund.updated, charge.refunded, customer.subscription.updated und customer.subscription.deleted (der Bildschirm „Stripe verbinden“ listet sie auf). Events fließen in Verifizierung und Abgleich ein; COLVO handelt nie auf Grundlage eines unsignierten Events.
Paddle. Legen Sie in Paddle ein Benachrichtigungsziel mit der von COLVO angezeigten URL (/v1/webhooks/paddle/{connection_id}) und den Events adjustment.created, adjustment.updated, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed an. Der Header Paddle-Signature wird mit dem Secret Key des Ziels geprüft (Zeitstempel, die älter als 5 Minuten sind, werden abgelehnt). adjustment.updated schließt eine Erstattung ab, die auf Paddles Prüfung gewartet hat; eine abgelehnte Erstattung eröffnet einen Vorfall und gibt das Budget frei.
Chargebee. Chargebee schützt Webhooks mit HTTP Basic Auth statt mit einer Signatur: Legen Sie in Chargebee einen Webhook mit der URL (/v1/webhooks/chargebee/{connection_id}), dem Benutzernamen colvo und dem Passwort an, das COLVO beim Verbinden angezeigt hat, sowie den Events 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. Ein falsches oder fehlendes Passwort wird abgelehnt (401). Events sind nur Hinweise: Die Verifizierung liest Chargebee immer erneut.
Änderungen außerhalb von COLVO
Eine Erstattung oder Kündigung, die durch keine Operation oder Beobachtung von COLVO erklärt wird – ein alter Schlüssel, der noch im Agenten steckt, eine manuelle Erstattung im Dashboard –, eröffnet einen UNEXPECTED_ACTION-Vorfall und löst Ihre Alerts aus, nach einer zweiten Prüfung eine Minute später (unser eigener Schreibvorgang könnte noch laufen). Pro Verbindung: auto (Standard: Alert erst, nachdem Guard auf diesem Konto ausgeführt hat, sodass reine Beobachtungsverbindungen still bleiben), alert oder ignore – PATCH /v1/projects/{id}/connections/{connection_id} mit { "out_of_band": "alert" } oder die Auswahl auf der Projektseite.
Ausgehend: Alert-Kanäle
GET / POST /v1/alert-channels, DELETE /v1/alert-channels/{id}, POST /v1/alert-channels/{id}/test. Pro Projekt; Events: 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? }Webhook-Zustellungen sind JSON mit einem X-Colvo-Signature-Header (HMAC-SHA256), wenn ein Secret gesetzt ist, und werden mit Backoff wiederholt. Slack nutzt eine Incoming-Webhook-URL; E-Mail nutzt Resend mit der COLVO-Vorlage.