Webhooks

Webhooks permitem que voce receba notificacoes HTTP em tempo real quando eventos ocorrem na sua conta GoConverso. Use-os para sincronizar dados com sistemas externos, disparar automacoes ou construir integracoes personalizadas.

Como os webhooks funcionam

Quando um evento ocorre (como um pagamento bem-sucedido ou um novo agendamento), o GoConverso envia uma requisicao HTTP POST para a URL do endpoint configurado com um payload JSON descrevendo o evento.

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

Seu endpoint deve:

1. Aceitar requisicoes POST
2. Retornar um codigo de status 2xx em ate 30 segundos
3. Verificar a assinatura do webhook para confirmar a autenticidade
4. Processar o evento de forma assincrona se exigir computacao pesada

Webhooks do Stripe

Os webhooks do Stripe lidam com todos os eventos relacionados a pagamentos. O GoConverso processa estes atraves de uma edge function dedicada (stripe-webhook) que valida assinaturas, atualiza o status de assinatura e registra transacoes.

Eventos do Stripe suportados

Configurando webhooks do Stripe

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

STRIPE_WEBHOOK_SECRET=whsec_1234567890abcdef

Payload do webhook do Stripe

Aqui esta um exemplo de payload para um 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
}

Verificacao de assinatura

O GoConverso verifica cada webhook do Stripe recebido usando o cabecalho stripe-signature. Isso impede que requisicoes falsificadas cheguem a sua logica de processamento.

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 notificacao de agendamento

O GoConverso pode enviar notificacoes via webhook quando eventos de agendamento ocorrem. Estes sao entregues atraves de Supabase Edge Functions.

Eventos de agendamento suportados

Payload do evento de agendamento

{
  "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"
  }
}

Construindo um receptor de webhook

Aqui esta um exemplo minimo de um receptor de webhook em 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 retentativa

Se o seu endpoint nao retornar um codigo de status 2xx, o GoConverso tenta reenviar o webhook:

Apos 5 tentativas falhas, o webhook e marcado como falho. Voce pode visualizar entregas falhas e tenta-las novamente manualmente a partir do Painel do Stripe.

Testando webhooks localmente

Durante o desenvolvimento, use o Stripe CLI  para encaminhar webhooks para seu ambiente 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

Melhores praticas de seguranca

• Sempre verifique assinaturas — Nunca processe um webhook sem antes verificar o cabecalho de assinatura. Isso impede que atacantes enviem eventos falsos para o seu endpoint.
• Use HTTPS — Endpoints de webhook devem usar HTTPS em producao. Endpoints HTTP nao receberao eventos.
• Responda rapidamente — Retorne uma resposta 2xx em ate 30 segundos. Se o processamento levar mais tempo, confirme o recebimento imediatamente e processe de forma assincrona.
• Trate duplicatas — Webhooks podem ser entregues mais de uma vez. Use o id do evento para deduplicar.
• Registre tudo — Armazene os payloads brutos dos webhooks para depuracao. Isso e inestimavel ao solucionar problemas de integracao.

Para mais informacoes sobre integracao de pagamentos, veja a documentacao do Stripe Checkout . Para autenticacao da API, veja o guia de Autenticacao.