Webhooks

Los webhooks te permiten recibir notificaciones HTTP en tiempo real cuando ocurren eventos en tu cuenta de GoConverso. Usalos para sincronizar datos con sistemas externos, activar automatizaciones o construir integraciones personalizadas.

Como funcionan los webhooks

Cuando ocurre un evento (como un pago exitoso o una nueva reserva), GoConverso envia una solicitud HTTP POST a la URL de tu endpoint configurado con un payload JSON que describe el evento.

Evento GoConverso  -->  HTTP POST  -->  Tu Endpoint
                        (payload JSON)

Tu endpoint debe:

1. Aceptar solicitudes POST
2. Devolver un codigo de estado 2xx dentro de 30 segundos
3. Verificar la firma del webhook para confirmar autenticidad
4. Procesar el evento de forma asincrona si requiere computacion pesada

Webhooks de Stripe

Los webhooks de Stripe manejan todos los eventos relacionados con pagos. GoConverso los procesa a traves de una edge function dedicada (stripe-webhook) que valida firmas, actualiza el estado de suscripciones y registra transacciones.

Eventos de Stripe soportados

Configuracion de webhooks de Stripe

https://<project-id>.supabase.co/functions/v1/stripe-webhook

STRIPE_WEBHOOK_SECRET=whsec_1234567890abcdef

Payload del webhook de Stripe

Aqui hay un ejemplo de payload para un evento checkout.session.completed:

{
  "id": "evt_1OqY4z2eZvKYlo2C8G9vU1qA",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_test_a1b2c3d4",
      "object": "checkout.session",
      "customer": "cus_Px7k9abcde",
      "customer_email": "user@example.com",
      "mode": "subscription",
      "payment_status": "paid",
      "status": "complete",
      "subscription": "sub_1OqY4z2eZvKYlo2C",
      "metadata": {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "plan": "plus"
      },
      "amount_total": 4900,
      "currency": "usd"
    }
  },
  "created": 1706540400
}

Verificacion de firma

GoConverso verifica cada webhook entrante de Stripe usando el encabezado stripe-signature. Esto previene que solicitudes falsificadas lleguen a tu logica de procesamiento.

import Stripe from 'stripe'
 
const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY'))
 
const signature = request.headers.get('stripe-signature')
const body = await request.text()
 
const event = stripe.webhooks.constructEvent(
  body,
  signature,
  Deno.env.get('STRIPE_WEBHOOK_SECRET')
)
 
// event is now verified and safe to process

Webhooks de notificacion de reservas

GoConverso puede enviar notificaciones de webhook cuando ocurren eventos de reservas. Estos se entregan a traves de Supabase Edge Functions.

Eventos de reserva soportados

Payload del evento de reserva

{
  "event": "booking.created",
  "timestamp": "2026-02-01T14:30:00.000Z",
  "data": {
    "booking_id": "b7e8f9a0-1234-5678-abcd-ef0123456789",
    "professional_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_name": "John Smith",
    "client_email": "john@example.com",
    "client_phone": "+1-555-0100",
    "service": {
      "id": "svc_abc123",
      "name": "Haircut",
      "price": 35.00,
      "duration": 30,
      "currency": "USD"
    },
    "scheduled_at": "2026-02-05T10:00:00.000Z",
    "status": "confirmed",
    "notes": "First time client, prefers short on sides"
  }
}

Construir un receptor de webhooks

Aqui hay un ejemplo minimo de un receptor de webhooks en Node.js:

const express = require('express')
const app = express()
 
app.use(express.json())
 
app.post('/webhooks/goconverso', (req, res) => {
  const event = req.body
 
  switch (event.event) {
    case 'booking.created':
      console.log('New booking:', event.data.booking_id)
      // Sync to your CRM, send a Slack notification, etc.
      break
 
    case 'booking.cancelled':
      console.log('Booking cancelled:', event.data.booking_id)
      // Update your calendar, notify staff, etc.
      break
 
    default:
      console.log('Unhandled event:', event.event)
  }
 
  // Always return 200 to acknowledge receipt
  res.status(200).json({ received: true })
})
 
app.listen(3000, () => {
  console.log('Webhook receiver running on port 3000')
})

Politica de reintentos

Si tu endpoint no devuelve un codigo de estado 2xx, GoConverso reintenta la entrega del webhook:

Despues de 5 intentos fallidos, el webhook se marca como fallido. Puedes ver las entregas fallidas y reintentarlas manualmente desde el Panel de Stripe.

Probar webhooks localmente

Durante el desarrollo, usa la CLI de Stripe  para reenviar webhooks a tu entorno local:

# Install and login to the Stripe CLI
stripe login
 
# Forward events to your local Supabase edge function
stripe listen --forward-to localhost:54321/functions/v1/stripe-webhook
 
# Trigger a test event
stripe trigger checkout.session.completed

Mejores practicas de seguridad

• Siempre verifica las firmas — Nunca proceses un webhook sin verificar primero el encabezado de firma. Esto previene que atacantes envien eventos falsos a tu endpoint.
• Usa HTTPS — Los endpoints de webhook deben usar HTTPS en produccion. Los endpoints HTTP no recibiran eventos.
• Responde rapidamente — Devuelve una respuesta 2xx dentro de 30 segundos. Si el procesamiento toma mas tiempo, confirma la recepcion inmediatamente y procesa de forma asincrona.
• Maneja duplicados — Los webhooks pueden entregarse mas de una vez. Usa el id del evento para deduplicar.
• Registra todo — Almacena los payloads crudos de webhook para depuracion. Esto es invaluable al solucionar problemas de integracion.

Para mas informacion sobre la integracion de pagos, consulta la documentacion de Stripe Checkout . Para autenticacion de la API, consulta la guia de Autenticacion.