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

# Configurando webhooks

> Como configurar URL e secret de webhook.

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

```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://meuapp.com/webhooks/astronpay",
    "webhookSecret": "meu-secret-min-8-chars"
  }'
```

Resposta:

```json theme={null}
{
  "webhookUrl": "https://meuapp.com/webhooks/astronpay",
  "webhookSecretConfigured": true
}
```

<Warning>
  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.
</Warning>

## Atualizar apenas a URL

```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://meuapp.com/nova-url" }'
```

## Rotacionar o secret

Para rotacionar sem mudar a URL, envie apenas `webhookSecret`:

```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 '{ "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

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

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

* [Eventos emitidos](/webhooks/events)
* [Validação de assinatura](/webhooks/validation)