Skip to main content
Webhooks são o canal assíncrono pelo qual a Astron Pay notifica seu backend sobre mudanças de estado (ordens, KYC, liquidações, etc.).

Visão geral

  • Configure URL + secret via PATCH /api/v1/webhook/config (ver Guia de configuração).
  • Os eventos chegam como POST com JSON no body.
  • Headers incluem X-Astronpay-Signature (HMAC SHA-256 do body bruto) e X-Astronpay-Delivery (ID único da entrega).
  • Responda 200 dentro de 10 s. Qualquer outro status ou timeout dispara retry.

Configuração

Configure URL e secret via API:
Consultar configuração atual:
Os campos aceitos pelo PATCH são webhookUrl e webhookSecret. Passe null para remover um valor.

Headers enviados

Payload

Todo evento segue este formato:
Os campos de nível raiz variam por evento. Schemas por tipo: Eventos.

Retentativas

A Astron Pay retenta com backoff exponencial por até 24 h. Após isso, o evento é descartado.
Seu endpoint deve responder com 2xx em até 10 segundos. Processe eventos de forma assíncrona se necessário.

Idempotência

O campo deliveryId (e o header X-Astronpay-Delivery) identifica unicamente cada tentativa de entrega. O mesmo evento pode ser entregue mais de uma vez em caso de falha de rede — armazene o deliveryId e ignore duplicatas.

Segurança

Verifique a assinatura antes de processar qualquer payload. Ver Validação de assinatura.