Skip to Content

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

  1. Evento ocorre no gateway (ex.: pagamento confirmado pelo banco)
  2. Gateway envia HTTP POST para /api/webhooks/payment/{gateway} no Opero
  3. Opero identifica o tenant pelo webhook secret (parametro webhookSecret na URL ou HTTP Basic) e valida o evento
  4. Opero processa o evento e atualiza os dados internos
  5. Opero responde com HTTP 200 — inclusive quando descarta o evento, para que o gateway nao reenvie
  6. Se o Opero nao responder, o gateway tenta novamente (retry), conforme a politica de cada gateway

Eventos suportados

Gateways processados

GatewayConfirmam o pagamentoMarcam falha
Pagar.mecharge.paid, order.paidcharge.payment_failed, order.payment_failed, charge.antifraud_reproved, charge.expired, charge.canceled, order.canceled
Mercado Pagopayment.* (o status e consultado no Mercado Pago)payment.* com pagamento recusado ou cancelado
GetNetAPPROVED_TRANSACTIONS, CAPTURED_TRANSACTIONS, PAYMENT_APPROVED, PAIDREJECTED_TRANSACTIONS, CANCELLED_TRANSACTIONS, PAYMENT_DENIED, EXPIRED
Abacate Paybilling.paidbilling.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:

GatewayMetodo de validacao
Stripe ConnectAssinatura via header Stripe-Signature
Mercado PagoHeader x-signature com HMAC; o status e relido no Mercado Pago
Pagar.meUsuario e senha (HTTP Basic); sem credenciais, o status e relido no Pagar.me
GetNetWebhook secret (HTTP Basic ou parametro na URL)
Abacate PayParametro 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 possivelSolucao
URL de webhook incorretaConfira a URL exibida ao salvar o gateway em Configuracoes > Gateways de Pagamento
Firewall bloqueandoLibere os IPs do gateway no firewall
SSL expiradoRenove o certificado SSL do servidor
Gateway em sandboxWebhooks de sandbox vao para URL de sandbox

Webhook chegou mas falhou

Causa possivelSolucao
Secret invalidoVerifique se o webhook secret (ou usuario e senha) cadastrado no gateway e o mesmo do Opero
Evento desconhecidoVerifique se o tipo de evento e suportado
Transacao nao encontradaO evento se refere a uma cobranca que nao foi criada pelo Opero
Erro internoConsulte os logs do servidor para detalhes

Boas praticas

  1. Cadastre o webhook ao criar o gateway — A URL e o secret sao exibidos uma unica vez, ao salvar
  2. Mantenha secrets atualizados — Ao editar as credenciais do gateway, confirme que o secret cadastrado no gateway continua valido
  3. Teste em sandbox primeiro — Simule eventos antes de ir para producao
Last updated on