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

# Introdução aos Webhooks

> Entenda como funcionam os webhooks na Autorizou e por que usá-los

## O que são Webhooks?

Webhooks são notificações HTTP automáticas enviadas pela Autorizou para sua aplicação sempre que um evento importante acontece, como a confirmação de um pagamento, uma recusa ou um estorno.

Em vez de você precisar ficar consultando nossa API repetidamente para verificar mudanças de status (polling), nós enviamos as informações diretamente para você em tempo real.

## Por que usar Webhooks?

<CardGroup cols={2}>
  <Card title="Tempo Real" icon="bolt">
    Receba notificações instantâneas sobre eventos importantes
  </Card>

  <Card title="Eficiência" icon="gauge-high">
    Elimine a necessidade de polling constante da API
  </Card>

  <Card title="Escalabilidade" icon="arrow-up-right-dots">
    Processe eventos de forma assíncrona e escalável
  </Card>

  <Card title="Confiabilidade" icon="shield-check">
    Sistema de retry automático garante a entrega
  </Card>
</CardGroup>

## Como Funcionam na Autorizou

### Fluxo de Notificação

```mermaid theme={null}
sequenceDiagram
    participant Cliente
    participant Autorizou
    participant Seu Servidor
    
    Cliente->>Autorizou: Realiza pagamento
    Autorizou->>Autorizou: Processa pagamento
    Autorizou->>Seu Servidor: POST webhook (evento)
    Seu Servidor-->>Autorizou: HTTP 200 OK
    Seu Servidor->>Seu Servidor: Processa evento
```

<Steps>
  <Step title="Um evento ocorre">
    Um pagamento é autorizado, recusado, ou qualquer outro evento configurado
  </Step>

  <Step title="Autorizou envia notificação">
    Fazemos uma requisição POST para sua URL com os dados do evento
  </Step>

  <Step title="Você responde">
    Seu servidor confirma o recebimento com HTTP 200 OK
  </Step>

  <Step title="Você processa">
    Atualiza seu sistema baseado no evento recebido
  </Step>
</Steps>

## Garantias de Entrega

### Sistema de Retry Automático

Se seu servidor não responder ou retornar erro, tentamos reenviar automaticamente:

* **3 tentativas automáticas**
* **Intervalo crescente** entre tentativas (backoff exponencial)
* Primeira retry: \~1 minuto após falha
* Segunda retry: \~5 minutos após primeira falha
* Terceira retry: \~10 minutos após segunda falha

<Warning>
  Após 3 tentativas falhadas, o webhook é marcado como **suspended** e para de enviar notificações. Você precisará reativá-lo manualmente.
</Warning>

## Requisitos Técnicos

Para receber webhooks, seu endpoint deve:

<AccordionGroup>
  <Accordion title="Aceitar requisições POST com JSON" icon="code">
    O webhook será enviado como POST com `Content-Type: application/json`
  </Accordion>

  <Accordion title="Responder HTTP 200 para sucesso" icon="check">
    Qualquer status 2xx é considerado sucesso. Outros códigos acionam retry.
  </Accordion>

  <Accordion title="Responder em até 30 segundos" icon="clock">
    Se ultrapassar 30 segundos, consideramos timeout e tentamos reenviar.
  </Accordion>

  <Accordion title="Usar HTTPS em produção" icon="lock">
    URLs HTTP só são permitidas em ambiente de testes (sandbox).
  </Accordion>

  <Accordion title="Processar de forma idempotente" icon="rotate">
    O mesmo evento pode ser enviado mais de uma vez. Use o ID do evento para evitar duplicatas.
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={3}>
  <Card title="Configurar Webhooks" icon="gear" href="/api-reference/webhooks/configuration">
    Aprenda a configurar webhooks via Dashboard
  </Card>

  <Card title="Eventos Disponíveis" icon="bell" href="/api-reference/webhooks/events">
    Veja todos os eventos que você pode receber
  </Card>

  <Card title="Estrutura dos Payloads" icon="code" href="/api-reference/webhooks/payload-structure">
    Entenda a estrutura dos dados recebidos
  </Card>
</CardGroup>