Webhooks de Pagamento
Os webhooks sao notificacoes automaticas que os gateways de pagamento enviam ao Opero sempre que um evento relevante ocorre — pagamento confirmado, estorno processado, chargeback aberto, etc. O Opero processa esses eventos para atualizar reservas, lancamentos financeiros e status de pagamento em tempo real.
Como funcionam os webhooks?
┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Gateway (Stripe │────▸│ Opero Payment │────▸│ Modulos │
│ MercadoPago, │ │ Webhook Handler│ │ internos │
│ Cielo, etc.) │ │ │ │ │
│ │ │ 1. Recebe evento │ │ Reservas │
│ Evento ocorreu: │ │ 2. Valida assin. │ │ Financeiro │
│ payment.succeeded│ │ 3. Processa │ │ Notificacoes │
│ │ │ 4. Responde 200 │ │ │
└──────────────────┘ └──────────────────┘ └──────────────┘Fluxo detalhado
- Evento ocorre no gateway (ex.: pagamento confirmado pelo banco)
- Gateway envia HTTP POST para a URL de webhook do Opero
- Opero valida a assinatura criptografica do evento (previne fraude)
- Opero processa o evento e atualiza os dados internos
- Opero responde com HTTP 200 (confirmando o recebimento)
- Se o Opero nao responder, o gateway tenta novamente (retry)
Eventos suportados
Stripe
| Evento | Descricao | Acao no Opero |
|---|---|---|
payment_intent.succeeded | Pagamento confirmado | Atualiza reserva para “Pago”, cria lancamento contabil |
payment_intent.payment_failed | Pagamento falhou | Notifica hospede e recepcionista |
payment_intent.canceled | Pagamento cancelado | Reverte status da reserva para “Pendente” |
charge.refunded | Estorno total processado | Cria lancamento reverso, atualiza status |
charge.refund.updated | Estorno parcial atualizado | Atualiza valor do estorno no AR |
charge.dispute.created | Chargeback aberto | Alerta gestor, registra no financeiro |
charge.dispute.closed | Chargeback encerrado | Atualiza resultado (ganho/perda) |
payout.paid | Payout liquidado na conta bancaria | Atualiza status de liquidacao |
payout.failed | Payout falhou | Alerta gestor financeiro |
account.updated | Conta conectada atualizada | Atualiza status de onboarding |
Outros gateways
Cada gateway tem seus proprios nomes de eventos, mas o Opero os normaliza internamente:
| Evento normalizado | Descricao |
|---|---|
payment.confirmed | Pagamento confirmado (qualquer gateway) |
payment.failed | Pagamento falhou |
payment.refunded | Estorno processado |
payment.disputed | Contestacao aberta |
payout.completed | Liquidacao na conta bancaria |
Validacao de seguranca
Cada gateway assina seus webhooks de forma diferente. O Opero valida a assinatura antes de processar qualquer evento:
| Gateway | Metodo de validacao |
|---|---|
| Stripe | Assinatura HMAC-SHA256 via header Stripe-Signature |
| MercadoPago | Header x-signature com HMAC |
| PagSeguro | Token de verificacao no header |
| Cielo | IP whitelist + token |
| Adyen | HMAC-SHA256 via header hmac-signature |
Seguranca: Se a assinatura nao for valida, o evento e rejeitado com HTTP 401 e registrado no log de seguranca. Isso impede que atacantes enviem eventos falsos.
Retry logic (tentativas de reenvio)
Se o Opero nao responder com HTTP 200 (ou 2xx), o gateway tenta novamente:
Estrategia de retry do Stripe
| Tentativa | Intervalo |
|---|---|
| 1 | Imediata |
| 2 | 5 minutos |
| 3 | 30 minutos |
| 4 | 2 horas |
| 5 | 5 horas |
| 6 | 10 horas |
| 7 | 24 horas |
| 8+ | A cada 24 horas por ate 3 dias |
Apos todas as tentativas, o evento e marcado como falho no dashboard do Stripe.
Idempotencia
O Opero processa cada evento de forma idempotente: se o mesmo evento for recebido mais de uma vez (por retry), ele nao e processado novamente. Isso e garantido pelo event_id unico de cada webhook.
Monitoramento de webhooks
Dashboard de eventos
Acesse Pagamentos > Webhooks para ver:
| Coluna | Descricao |
|---|---|
| Data/hora | Quando o evento foi recebido |
| Gateway | De qual gateway veio |
| Tipo | Tipo do evento (payment.succeeded, etc.) |
| Status | Processado, falhou, ignorado |
| Reserva | Reserva associada (se aplicavel) |
| Tentativa | Numero da tentativa (1 = primeira) |
| Tempo de processamento | Quanto tempo o Opero levou para processar |
Alertas automaticos
O sistema envia alertas quando:
- Taxa de falha alta: Mais de 5% dos webhooks falharam nas ultimas 24h
- Atraso de processamento: Webhooks levando mais de 30 segundos para processar
- Evento critico falhou: Chargeback, estorno ou payout falharam
Troubleshooting
Webhook nao chegou
| Causa possivel | Solucao |
|---|---|
| URL de webhook incorreta | Verifique a URL em Configuracoes > Pagamentos > Webhooks |
| Firewall bloqueando | Libere os IPs do gateway no firewall |
| SSL expirado | Renove o certificado SSL do servidor |
| Gateway em sandbox | Webhooks de sandbox vao para URL de sandbox |
Webhook chegou mas falhou
| Causa possivel | Solucao |
|---|---|
| Assinatura invalida | Verifique se o webhook secret esta correto |
| Evento desconhecido | Verifique se o tipo de evento e suportado |
| Erro interno | Consulte os logs do servidor para detalhes |
| Timeout de processamento | Otimize o handler (deve responder em < 5s) |
Reprocessar um webhook
Se um webhook falhou e voce corrigiu o problema:
- Acesse Pagamentos > Webhooks > Historico
- Localize o evento falho
- Clique em “Reprocessar”
- O sistema tenta processar o evento novamente
Boas praticas
- Monitore diariamente — Webhooks sao o coracao da integracao; falhas silenciosas geram inconsistencias
- Configure alertas — Nao dependa de verificacao manual
- Mantenha secrets atualizados — Ao rotacionar chaves no gateway, atualize no Opero imediatamente
- Teste em sandbox primeiro — Simule eventos antes de ir para producao
- Mantenha logs por 90 dias — Para auditoria e troubleshooting de chargebacks