Skip to main content
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

curl -X PATCH https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://meuapp.com/webhooks/astronpay",
    "webhookSecret": "meu-secret-min-8-chars"
  }'
Resposta: 
{
  "webhookUrl": "https://meuapp.com/webhooks/astronpay",
  "webhookSecretConfigured": true
}
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

curl -X PATCH https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://meuapp.com/nova-url" }'

​
Rotacionar o secret

Para rotacionar sem mudar a URL, envie apenas webhookSecret: 
curl -X PATCH https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "webhookSecret": "novo-secret-min-8-chars" }'
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

curl https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
Retorna URL atual e webhookSecretConfigured: true|false.

​
Removendo a configuração

Passe null para limpar URL ou secret: 
curl -X PATCH https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": null }'

​
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