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:
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://meusite.com/webhooks/astronpay",
"webhookSecret": "minha-chave-secreta-minimo-8-chars"
}'
curl https://api.astronpay.co/api/v1/webhook/config \
-H "x-api-key: $API_KEY" \
-H "x-api-secret: $API_SECRET"
PATCH são webhookUrl e webhookSecret. Passe null para remover um valor.
| Header | Descrição |
|---|
X-Astronpay-Signature | sha256=<hmac-hex> — assinatura HMAC-SHA256 do body bruto |
X-Astronpay-Delivery | ID único desta entrega (UUID) — use para idempotência |
X-Astronpay-Event | Nome do evento (ex.: order.completed) |
Content-Type | application/json |
Payload
Todo evento segue este formato:
{
"event": "order.completed",
"orderId": "ord_uuid",
"externalId": "meu-pedido-123",
"type": "PAYIN",
"status": "COMPLETED",
"timestamp": "2026-04-16T18:31:12.000Z",
"deliveryId": "uuid-da-entrega"
}
Retentativas
A Astron Pay retenta com backoff exponencial por até 24 h. Após isso, o evento é descartado.
| Tentativa | Delay aproximado |
|---|
| 1 | Imediato |
| 2 | 30 s |
| 3 | 2 min |
| 4 | 10 min |
| 5 | 1 h |
| 6 | 4 h |
| 7 | 12 h |
| 8 | 24 h (última) |
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. 