Webhooks notificam seu backend quando ordens mudam de estado. Você configura a URL de destino e um secret para validação da assinatura.
Configuração inicial
Resposta:
O secret nunca é retornado pela API — você define o valor que quiser (mínimo 8 caracteres). Armazene-o em um cofre seguro e use-o para verificar a assinatura dos webhooks recebidos. Para rotacionar, basta enviar um novo webhookSecret na mesma requisição.
Atualizar apenas a URL
Rotacionar o secret
Para rotacionar sem mudar a URL, envie apenas webhookSecret:
O secret anterior é invalidado imediatamente após essa chamada.
Requisitos da URL
- HTTPS obrigatório em produção.
- Precisa responder 200 dentro de 10 s. Respostas 4xx/5xx provocam retentativas.
- Deve ser idempotente: retentativas podem entregar o mesmo evento mais de uma vez.
- IPs privados e localhost são bloqueados.
Retry
Em caso de falha (status ≠ 2xx ou timeout), a plataforma retenta com backoff exponencial por até 24 h. Após isso, o evento é marcado como falho e não será entregue novamente.
Consultando o status
Retorna URL atual e webhookSecretConfigured: true|false.
Removendo a configuração
Passe null para limpar URL ou secret:
Logs de entrega
O dashboard (app.astronpay.co) mostra o histórico de envios, latência e status. Use-o para depurar falhas.
Próximos passos
