Receba avisos de eventos e saiba quais cuidados e limitações existem nesta versão.
Em Integrações, informe a URL receptora, selecione os eventos e habilite o destino. A configuração pertence ao vendedor. Endereços locais e privados são bloqueados por padrão; para testes locais controlados, o operador pode habilitar WEBHOOK_ALLOW_LOCAL=true.
Prefira HTTPS. O servidor verifica o destino também na entrega. A API atual aceita URLs HTTP e HTTPS; não confunda recomendação de HTTPS com uma exigência já aplicada pelo código.
| Evento | Significado |
|---|---|
| charge.paid | Cobrança confirmada. |
| charge.expired | Cobrança expirada. |
| withdrawal.completed | Saque concluído. |
| withdrawal.failed | Saque falhou. |
| refund.completed | Devolução concluída. |
| refund.failed | Devolução falhou. |
O corpo contém id e event, além dos campos do evento. X-Movvi-Event identifica o tipo; X-Movvi-Timestamp é o instante Unix em segundos. X-Movvi-Signature contém o HMAC SHA-256 em hexadecimal de timestamp + ponto + corpo JSON exato, usando o segredo do endpoint. Não existe prefixo v1=.
O receptor deve verificar a assinatura sobre os bytes recebidos, antes de reserializar JSON; limitar a idade do timestamp; comparar em tempo constante e rejeitar assinaturas inválidas. Isso só pode ser habilitado depois de disponibilizar o segredo por um fluxo seguro.
A fila persiste os avisos e realiza até seis tentativas. As esperas entre as tentativas são de 1, 5, 15, 60 e 180 minutos. Resposta HTTP de sucesso encerra a entrega; falhas esgotadas ficam como dropped.
O receptor deve persistir o evento antes de retornar sucesso e deduplicar pelo id. Eventos podem se repetir; consulte o estado da cobrança e torne também a entrega do produto idempotente.
Consulte /webhook/deliveries para histórico de status, tentativas e erros. A listagem atual traz até 50 registros. Não existe endpoint público de reenvio manual.
A rota /providers/{provider}/events é uma entrada interna do provedor, com outra assinatura. Não a use para confirmar pagamentos em nome do comprador.