Skip to main content

Visão Geral

Webhooks permitem que sua aplicação receba notificações automáticas quando eventos importantes ocorrem na API Uvvipague, como mudanças de status de pagamento, liquidação de débitos e conclusão de consultas.
Comunicação Assíncrona: Os webhooks são enviados de forma assíncrona. Configure sua URL para receber as notificações automaticamente.
Correlacionando Requisições e Webhooks: Todos os webhooks incluem o campo externalId que você enviou na requisição original. Use este campo para identificar qual requisição gerou cada webhook. Se você não enviar um externalId, a API gerará um automaticamente, mas é altamente recomendado que você envie seus próprios IDs únicos.

Cadastro de Webhook

Endpoint

Parâmetros

string
required
URL do endpoint que receberá as notificações webhook. Deve ser uma URL válida e acessível publicamente.Exemplo: https://sua-api.com.br/webhook/uvvipague

Headers Obrigatórios

string
required
Sua API Key para autenticação

Exemplo de Requisição

Resposta de Sucesso

Política de Retentativas

A Uvvipague implementa uma política robusta de retentativas para garantir que você receba as notificações:
1

Tentativa Inicial

Enviamos a primeira requisição imediatamente após o evento ocorrer.
2

1ª Retentativa - 15 minutos

Se não recebermos resposta 200, tentamos novamente após 15 minutos.
3

2ª Retentativa - 60 minutos

Segunda tentativa após 60 minutos da tentativa inicial.
4

3ª Retentativa - 90 minutos

Terceira e última tentativa após 90 minutos da tentativa inicial.
5

Após 3 Retentativas

Após as 3 retentativas sem sucesso, nenhuma nova tentativa será realizada.O cliente precisará consultar o status manualmente usando o transactionId ou o externalId enviado na requisição original.
Importante: Após 3 tentativas falhadas, você deve consultar o status do pedido manualmente através da API de consulta de pagamento.

Timeline de Retentativas

Recebendo Webhooks

Estrutura do Payload

Quando um evento ocorre, enviamos uma requisição POST para sua URL cadastrada:

Resposta Esperada

Seu endpoint deve retornar HTTP 200 para confirmar o recebimento:
Importante: Retorne 200 o mais rápido possível. Processe o webhook de forma assíncrona em sua aplicação para não bloquear a resposta.

Implementação do Endpoint

Exemplo Completo

Segurança

Validações Recomendadas

Valide que a requisição vem dos servidores da Uvvipague:
  • Verifique o IP de origem (lista fornecida pelo suporte)
  • Implemente whitelist de IPs
Valide a estrutura do payload antes de processar:
Implemente idempotência usando transactionId ou externalId:
Configure timeout adequado no seu servidor:
  • Responda em menos de 5 segundos
  • Processe de forma assíncrona
  • Use filas (Redis, RabbitMQ) para processamento

Consulta Manual de Status

Se todas as tentativas de webhook falharem, consulte o status manualmente:

Endpoint de Consulta

Testando Webhooks

Ferramentas Úteis

Webhook.site

Use webhook.site para testar e visualizar webhooks durante o desenvolvimento.

ngrok

Use ngrok para expor seu localhost e receber webhooks em desenvolvimento.

RequestBin

Use RequestBin para inspecionar payloads de webhook.

Postman

Simule webhooks usando Postman para testar seu endpoint.

Exemplo com ngrok

Boas Práticas

1

Responda Rapidamente

Retorne HTTP 200 em menos de 5 segundos. Processe o webhook de forma assíncrona.
2

Implemente Idempotência

Use transactionId ou externalId para evitar processar o mesmo webhook múltiplas vezes.
3

Log Tudo

Registre todos os webhooks recebidos para auditoria e debugging.
4

Use Filas

Implemente filas (Redis, RabbitMQ, SQS) para processar webhooks de forma resiliente.
5

Monitore Falhas

Configure alertas para webhooks que falharem após todas as retentativas.
6

Tenha Fallback

Implemente consulta periódica de status como fallback caso os webhooks falhem.

Próximos Passos

Fluxo Completo

Veja como integrar webhooks no fluxo completo

Consulta de Débitos

Entenda os tipos de resposta via webhook

ENUMs e Tipos

Consulte os tipos de eventos e status

Autenticação

Configure sua API Key