> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astronpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks — visão geral

> Eventos enviados pela Astron Pay ao seu backend.

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](/guides/webhook-setup)).
* 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:

```bash theme={null}
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"
  }'
```

Consultar configuração atual:

```bash theme={null}
curl https://api.astronpay.co/api/v1/webhook/config \
  -H "x-api-key: $API_KEY" \
  -H "x-api-secret: $API_SECRET"
```

Os campos aceitos pelo `PATCH` são `webhookUrl` e `webhookSecret`. Passe `null` para remover um valor.

## Headers enviados

| 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:

```json theme={null}
{
  "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"
}
```

Os campos de nível raiz variam por evento. Schemas por tipo: [Eventos](/webhooks/events).

## 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)    |

<Warning>
  Seu endpoint deve responder com `2xx` em até **10 segundos**. Processe eventos de forma assíncrona se necessário.
</Warning>

## 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](/webhooks/validation).