Webhooks
Dos direcciones: eventos de Stripe hacia COLVO para verificación y conciliación, y alertas de COLVO hacia Slack, email o tu propio webhook.
Entrantes: Stripe → COLVO
Cuando conectas una cuenta de Stripe a un proyecto, COLVO te da un endpoint de webhook para esa conexión:
POST https://colvo.app/v1/webhooks/stripe/{connection_id}Añádelo en el dashboard de Stripe con el secreto de firma que COLVO muestra una sola vez. Se verifica la firma de los eventos (stripe-signature), se añaden a una bandeja de entrada duradera y los procesa el worker; una firma ausente o no válida se rechaza (400), igual que los cuerpos de más de 1 MB (413). Suscríbete a refund.created, refund.updated, charge.refunded, customer.subscription.updated y customer.subscription.deleted (la pantalla Conectar Stripe los enumera). Los eventos alimentan la verificación y la conciliación; COLVO nunca actúa sobre un evento sin firmar.
Paddle. Añade en Paddle un destino de notificaciones con la URL que muestra COLVO (/v1/webhooks/paddle/{connection_id}) y los eventos adjustment.created, adjustment.updated, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed. El header Paddle-Signature se verifica con la clave secreta del destino (se rechazan los timestamps de más de 5 minutos). adjustment.updated completa un reembolso que esperaba la revisión de Paddle; un reembolso rechazado abre un incidente y libera el presupuesto.
Chargebee. Chargebee protege los webhooks con autenticación HTTP basic en lugar de una firma: añade en Chargebee un webhook con la URL (/v1/webhooks/chargebee/{connection_id}), el usuario colvo y la contraseña que COLVO te mostró al conectar, y los eventos 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 contraseña incorrecta o ausente se rechaza (401). Los eventos son solo pistas: la verificación siempre vuelve a leer Chargebee.
Cambios hechos fuera de COLVO
Un reembolso o una cancelación que ninguna operación u observación de COLVO explica (una clave antigua que sigue en el agente, un reembolso manual desde el Dashboard) abre un incidente UNEXPECTED_ACTION y dispara tus alertas, tras una segunda comprobación al cabo de un minuto (puede que nuestra propia escritura aún se esté confirmando). Por conexión: auto (por defecto: alerta solo cuando Guard ya ha ejecutado en esta cuenta, así las conexiones solo de observación no hacen ruido), alert o ignore: PATCH /v1/projects/{id}/connections/{connection_id} con { "out_of_band": "alert" }, o el selector de la página del proyecto.
Salientes: canales de alertas
GET / POST /v1/alert-channels, DELETE /v1/alert-channels/{id}, POST /v1/alert-channels/{id}/test. Por proyecto; eventos: 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? }Los envíos de webhook son JSON con un header HMAC-SHA256 X-Colvo-Signature cuando hay un secreto definido, y se reintentan con backoff. Slack usa una URL de incoming webhook; el email usa Resend con la plantilla de marca de COLVO.