Webhooks de Pagamento
Os webhooks sao notificacoes automaticas que os gateways de pagamento enviam ao Opero quando um evento relevante ocorre — pagamento confirmado, pagamento recusado, PIX expirado, etc. O Opero processa esses eventos para atualizar a transacao e o status de pagamento da reserva.
Como funcionam os webhooks?
┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Gateway (Pagar. │────▸│ Opero Payment │────▸│ Modulos │
│ me, Mercado │ │ Webhook Handler│ │ internos │
│ Pago, GetNet) │ │ │ │ │
│ │ │ 1. Recebe evento │ │ Transacao │
│ Evento ocorreu: │ │ 2. Valida origem │ │ Reserva │
│ pagamento pago │ │ 3. Processa │ │ Notificacoes │
│ │ │ 4. Responde 200 │ │ │
└──────────────────┘ └──────────────────┘ └──────────────┘Fluxo detalhado
- Evento ocorre no gateway (ex.: pagamento confirmado pelo banco)
- Gateway envia HTTP POST para
/api/webhooks/payment/{gateway}no Opero - Opero identifica o tenant pelo webhook secret (parametro
webhookSecretna URL ou HTTP Basic) e valida o evento - Opero processa o evento e atualiza os dados internos
- Opero responde com HTTP 200 — inclusive quando descarta o evento, para que o gateway nao reenvie
- Se o Opero nao responder, o gateway tenta novamente (retry), conforme a politica de cada gateway
Eventos suportados
Gateways processados
| Gateway | Confirmam o pagamento | Marcam falha |
|---|---|---|
| Pagar.me | charge.paid, order.paid | charge.payment_failed, order.payment_failed, charge.antifraud_reproved, charge.expired, charge.canceled, order.canceled |
| Mercado Pago | payment.* (o status e consultado no Mercado Pago) | payment.* com pagamento recusado ou cancelado |
| GetNet | APPROVED_TRANSACTIONS, CAPTURED_TRANSACTIONS, PAYMENT_APPROVED, PAID | REJECTED_TRANSACTIONS, CANCELLED_TRANSACTIONS, PAYMENT_DENIED, EXPIRED |
| Abacate Pay | billing.paid | billing.failed, billing.expired |
Webhooks de Stripe, Asaas, Stone e Rede ainda nao sao processados por este endpoint. Nesses casos, o status e conferido diretamente no gateway (veja Monitoramento).
Stripe Connect
O endpoint /api/connect-webhook recebe eventos das contas conectadas do Opero Payment e processa account.updated, que atualiza os indicadores Cobrancas, Repasses e Cadastro da conta. Os demais eventos sao apenas registrados em log.
Validacao de seguranca
Cada gateway se autentica de forma diferente. O Opero valida a origem antes de processar qualquer evento:
| Gateway | Metodo de validacao |
|---|---|
| Stripe Connect | Assinatura via header Stripe-Signature |
| Mercado Pago | Header x-signature com HMAC; o status e relido no Mercado Pago |
| Pagar.me | Usuario e senha (HTTP Basic); sem credenciais, o status e relido no Pagar.me |
| GetNet | Webhook secret (HTTP Basic ou parametro na URL) |
| Abacate Pay | Parametro webhookSecret na URL |
Seguranca: Se a validacao falhar, o evento e descartado e registrado no log do servidor; o endpoint de pagamentos responde HTTP 200 mesmo assim. No
/api/connect-webhook, uma assinatura invalida e rejeitada com HTTP 400.
Retry logic (tentativas de reenvio)
Se o Opero nao responder com HTTP 2xx (por exemplo, servidor indisponivel), cada gateway reenvia o evento conforme a sua propria politica de retry.
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 identificador do evento (ou por uma chave derivada do conteudo, quando o gateway nao envia um) e por uma verificacao de status: transacoes ja aprovadas ou ja com falha nao sao alteradas.
Monitoramento de webhooks
Nao ha painel de webhooks no dashboard. Os eventos ficam registrados no historico da transacao e nos logs do servidor.
Como complemento aos webhooks:
- Consulta de status: Enquanto o pagamento esta pendente, o portal consulta o status e o Opero confere a transacao no gateway
- Expiracao: A cada minuto, uma rotina confere com o gateway as cobrancas pendentes ja vencidas
Troubleshooting
Webhook nao chegou
| Causa possivel | Solucao |
|---|---|
| URL de webhook incorreta | Confira a URL exibida ao salvar o gateway em Configuracoes > Gateways de Pagamento |
| 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 |
|---|---|
| Secret invalido | Verifique se o webhook secret (ou usuario e senha) cadastrado no gateway e o mesmo do Opero |
| Evento desconhecido | Verifique se o tipo de evento e suportado |
| Transacao nao encontrada | O evento se refere a uma cobranca que nao foi criada pelo Opero |
| Erro interno | Consulte os logs do servidor para detalhes |
Boas praticas
- Cadastre o webhook ao criar o gateway — A URL e o secret sao exibidos uma unica vez, ao salvar
- Mantenha secrets atualizados — Ao editar as credenciais do gateway, confirme que o secret cadastrado no gateway continua valido
- Teste em sandbox primeiro — Simule eventos antes de ir para producao