Webhooks
Due direzioni: eventi Stripe verso COLVO per verifica e riconciliazione, e alert di COLVO verso Slack, email o il tuo webhook.
In entrata: Stripe → COLVO
Quando colleghi un account Stripe a un progetto, COLVO ti dà un endpoint webhook per quella connessione:
POST https://colvo.app/v1/webhooks/stripe/{connection_id}Aggiungilo nella dashboard di Stripe con il segreto di firma mostrato una sola volta in COLVO. La firma degli eventi viene verificata (stripe-signature), poi gli eventi vengono aggiunti a una inbox durevole ed elaborati dal worker; una firma mancante o non valida viene rifiutata (400), così come i body oltre 1 MB (413). Iscriviti a refund.created, refund.updated, charge.refunded, customer.subscription.updated e customer.subscription.deleted (la schermata Connetti Stripe li elenca). Gli eventi alimentano verifica e riconciliazione; COLVO non agisce mai su un evento non firmato.
Paddle. Aggiungi in Paddle una destinazione di notifica con l’URL mostrato da COLVO (/v1/webhooks/paddle/{connection_id}) e gli eventi adjustment.created, adjustment.updated, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed. L’header Paddle-Signature viene verificato con la chiave segreta della destinazione (i timestamp più vecchi di 5 minuti vengono rifiutati). adjustment.updated completa un rimborso in attesa della revisione di Paddle; un rimborso respinto apre un incidente e libera il budget.
Chargebee. Chargebee protegge i webhook con l’autenticazione HTTP basic invece che con una firma: aggiungi in Chargebee un webhook con l’URL (/v1/webhooks/chargebee/{connection_id}), lo username colvo e la password che COLVO ti ha mostrato al collegamento, e gli eventi 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. Una password errata o mancante viene rifiutata (401). Gli eventi sono solo indizi: la verifica rilegge sempre Chargebee.
Modifiche fatte fuori da COLVO
Un rimborso o una disdetta che nessuna operazione o osservazione di COLVO spiega — una vecchia chiave ancora nell’agente, un rimborso manuale dalla Dashboard — apre un incidente UNEXPECTED_ACTION e invia i tuoi alert, dopo un secondo controllo a un minuto di distanza (la nostra scrittura potrebbe essere ancora in corso). Per connessione: auto (predefinito: alert solo dopo che Guard ha eseguito su questo account, così le connessioni in sola osservazione restano silenziose), alert o ignore — PATCH /v1/projects/{id}/connections/{connection_id} con { "out_of_band": "alert" }, oppure il selettore nella pagina del progetto.
In uscita: canali di alert
GET / POST /v1/alert-channels, DELETE /v1/alert-channels/{id}, POST /v1/alert-channels/{id}/test. Per progetto; eventi: 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? }Le consegne webhook sono JSON con un header HMAC-SHA256 X-Colvo-Signature quando è impostato un segreto, e vengono ritentate con backoff. Slack usa un URL di incoming webhook; l’email usa Resend con il template di COLVO.