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

# Webhooks na Prática

> Receba notificações de pagamento de forma confiável e idempotente

Os **webhooks** são a forma recomendada de acompanhar o ciclo de vida de pagamentos
e assinaturas sem precisar ficar consultando a API. Sempre que o status de um
pagamento muda, a Autorizou envia um `POST` para a `notification_url` configurada
na cobrança.

<Note>
  Para a referência completa do payload e dos eventos, veja
  [Webhooks › Estrutura do Payload](/api-reference/webhooks/payload-structure) e
  [Webhooks › Eventos](/api-reference/webhooks/events).
</Note>

## Configurando a URL

Você pode definir a URL de notificação por cobrança, no campo `notification_url`
ao [Criar Pedido](/api-reference/charges/orders/create-order) ou
[Criar Assinatura](/api-reference/subscriptions/create-subscription).

## Boas práticas

<Steps>
  <Step title="Responda rápido (2xx)">
    Retorne `200` assim que receber o evento e processe de forma assíncrona. O
    timeout do remetente é curto.
  </Step>

  <Step title="Seja idempotente">
    O mesmo evento pode chegar mais de uma vez. Use o `id` do evento/pagamento
    como chave de deduplicação antes de aplicar efeitos colaterais.
  </Step>

  <Step title="Valide a origem">
    Confirme a assinatura/credencial do webhook antes de confiar no payload.
  </Step>

  <Step title="Trate reentregas">
    Eventos que falham são reenviados. Não trate um reenvio como um novo pagamento.
  </Step>
</Steps>

## Fluxo típico

```mermaid theme={null}
sequenceDiagram
    participant Z as Autorizou
    participant S as Seu servidor
    Z->>S: POST notification_url (evento)
    S-->>Z: 200 OK (imediato)
    S->>S: Processa de forma assíncrona (idempotente)
```

## Conferindo o estado real

Webhooks são notificações, não a fonte da verdade. Em caso de dúvida (ou perda de
evento), confirme o estado consultando o pagamento em
[Consultar Pagamento](/api-reference/charges/payments/get-payment).