Referência

A integração de Webhooks permite cadastrar endpoints HTTPS para receber notificações de eventos da ZeriqPay. Esta página é a referência conceitual do recurso; as operações HTTP ficam agrupadas em Gerenciamento na barra lateral.

​

Gerenciamento disponível

O submenu fechado Gerenciamento contém somente as operações de configuração do endpoint:

• Criar endpoint
• Listar endpoints
• Consultar endpoint
• Atualizar endpoint
• Revogar endpoint

​

Entregas e Reenvios

• Histórico de entregas
• Entregas do endpoint
• Consultar entrega
• Reenviar entrega
• Reenviar falhas

​

Fluxo recomendado

1. Crie um endpoint com uma URL pública usando HTTPS e selecione apenas os eventos necessários.
2. Armazene o segredo retornado pela criação em um cofre de segredos. Ele não deve ser colocado no frontend nem versionado.
3. Valide a assinatura recebida antes de processar o payload e responda rapidamente com um status HTTP de sucesso.
4. Use Consultar endpoint ou Listar endpoints para confirmar a configuração e o estado atual.
5. Para alterar URL, eventos ou status, use Atualizar endpoint. O array events enviado substitui a inscrição anterior.
6. Quando o endpoint não for mais necessário, use Revogar endpoint para interromper novos envios.

​

Segurança

• Use exclusivamente URLs https:// sob seu controle.
• Não exponha o segredo do endpoint em logs, respostas públicas ou código cliente.
• Faça a validação da assinatura antes de alterar saldo, liberar pedido ou mudar o estado de uma transação.
• Trate o mesmo evento mais de uma vez sem efeitos duplicados: callbacks podem ser repetidos ou reprocessados pela sua infraestrutura.
• Registre o identificador do evento, o tipo, a transação relacionada e o horário de processamento.

​

Escopo desta referência

Esta seção documenta o gerenciamento dos endpoints e o acompanhamento das entregas: criação, listagem, consulta, atualização, revogação, histórico, detalhes das tentativas e reenvios. Métricas agregadas e eventos de teste não fazem parte deste grupo. Todas as rotas exigem X-API-Key e utilizam a base URL https://api.zeriqpay.com.br. Cada página do submenu apresenta o contrato OpenAPI, parâmetros, exemplos de request e response, códigos de erro e boas práticas específicas.