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

# Configuração de Webhooks

> Aprenda a configurar webhooks para receber notificações de eventos

## Visão Geral

Existem duas formas de receber notificações via webhook na Autorizou:

1. **Webhook Global**: Configurado na Dashboard e recebe todos os eventos selecionados
2. **Notification URL**: URL específica por pagamento (configurada ao criar o pagamento)

<Info>
  A forma recomendada é configurar **Webhooks Globais** pela Dashboard, que
  oferece gerenciamento completo e histórico de disparos.
</Info>

***

## Configurando via Dashboard

### Passo a Passo

<Steps>
  <Step title="Acesse a Dashboard">
    Faça login na [Dashboard Autorizou](https://dash.autorizou.com.br)
  </Step>

  <Step title="Navegue até Webhooks">
    No menu lateral, acesse **Integrações → Webhooks**
  </Step>

  <Step title="Criar Novo Webhook">Clique no botão **"Criar Webhook"**</Step>

  <Step title="Preencha o Formulário">
    Configure os campos obrigatórios (veja detalhes abaixo)
  </Step>

  <Step title="Salvar">Clique em **"Salvar"** para ativar o webhook</Step>
</Steps>

### Campos de Configuração

<ParamField body="url" type="string" required>
  URL do seu endpoint que receberá as notificações.

  **Requisitos (validados no momento do envio):** deve ser **HTTPS** e **publicamente acessível**. Por
  segurança (anti-SSRF), a plataforma **não entrega** para `http://` nem para endereços privados/internos
  — `localhost`, `127.x`, `10.x`, `172.16–31.x`, `192.168.x`, link-local (`169.254.x`). Ao testar, use um
  túnel público (ex.: ngrok), não um endereço local.

  Exemplo: `https://seu-site.com.br/webhooks/autorizou`
</ParamField>

<ParamField body="description" type="string" required>
  Descrição para identificar o webhook Útil quando você tem múltiplos webhooks
  configurados Exemplo: `Webhook principal de produção`
</ParamField>

<ParamField body="events" type="array" required>
  Eventos que você deseja receber notificações **Selecione pelo menos um
  evento** A Dashboard mostra todos os eventos disponíveis organizados por
  categoria [Ver todos os eventos disponíveis](/api-reference/webhooks/events)
</ParamField>

<ParamField body="content_type_header" type="string" required>
  Formato do conteúdo enviado no webhook Opções disponíveis: -
  `application/json` (recomendado) - `application/x-www-form-urlencoded` Padrão:
  `application/json`
</ParamField>

<ParamField body="status" type="string" required>
  Status inicial do webhook Opções: - `enabled` - Ativo e enviando notificações

  * `disabled` - Desabilitado manualmente Padrão: `enabled`

  <Note>
    O status `suspended` é atribuído automaticamente pelo sistema após 3 falhas
    consecutivas
  </Note>
</ParamField>

<ParamField body="secret" type="string">
  Chave secreta opcional para validar requisições Recomendado para adicionar uma
  camada extra de segurança **Guarde em local seguro** - não será exibido
  novamente Exemplo: `whsec_abc123def456xyz789`
</ParamField>

***

## Gerenciando Webhooks na Dashboard

### Visualizar Webhooks

Na página de webhooks você pode:

<CardGroup cols={2}>
  <Card title="Ver URL e Status" icon="eye">
    Visualize a URL configurada e status atual
  </Card>

  <Card title="Ver Eventos" icon="bell">
    Confira quais eventos estão configurados
  </Card>

  <Card title="Editar Webhook" icon="pen">
    Atualize URL, eventos ou status
  </Card>

  <Card title="Excluir Webhook" icon="trash">
    Remova webhooks não utilizados
  </Card>
</CardGroup>

### Histórico de Disparos

Para cada webhook, você pode acessar o histórico completo de disparos:

* **Data e hora** de cada disparo
* **Evento** que disparou
* **Status** da entrega (delivered, failed, retrying, pending)
* **Código HTTP** da resposta
* **Número de tentativas**
* **Payload enviado**
* **Resposta recebida**

<Tip>Use o histórico de disparos para debug e monitoramento da integração</Tip>

***

## Status do Webhook

Um webhook pode ter os seguintes status:

<AccordionGroup>
  <Accordion title="enabled" icon="circle-check">
    **Ativo** Webhook está funcionando normalmente e enviando notificações Este
    é o status padrão ao criar um webhook
  </Accordion>

  <Accordion title="disabled" icon="circle-pause">
    **Desabilitado** Webhook foi desabilitado manualmente Não envia notificações
    até ser reativado Útil para manutenção temporária
  </Accordion>

  <Accordion title="suspended" icon="circle-xmark">
    **Suspenso** Webhook foi suspenso automaticamente pelo sistema após 3
    tentativas de entrega falhadas **Para reativar:** 1. Corrija o problema no
    seu endpoint 2. Atualize o webhook para status `enabled` na Dashboard
  </Accordion>
</AccordionGroup>

***

## Notification URL por Pagamento

Além dos webhooks globais, você pode especificar uma `notification_url` ao criar um pagamento individual.

### Quando Usar

* Quando cada pagamento precisa notificar URLs diferentes
* Para integrações com sistemas externos que fornecem URLs únicas
* Para testes ou ambientes temporários

### Exemplo ao Criar Pagamento

```json theme={null}
{
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "credit_card",
  "notification_url": "https://seu-site.com.br/pedidos/123/webhook",
  "card": {
    "number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "2025",
    "cvv": "123",
    "holder": "João Silva"
  },
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com"
  }
}
```

<Note>
  Se você tiver webhooks globais configurados **E** uma `notification_url` no
  pagamento, **ambos receberão as notificações**.
</Note>

***

## Content Type Header

O campo `content_type_header` define como o payload será enviado:

### application/json (Recomendado)

```http theme={null}
POST /webhooks/autorizou HTTP/1.1
Host: seu-site.com.br
Content-Type: application/json

{
  "event": "payment.authorized",
  "payment": { ... }
}
```

**Processamento:**

```php theme={null}
$payload = $request->json()->all();
// ou
$payload = json_decode($request->getContent(), true);
```

### application/x-www-form-urlencoded

```http theme={null}
POST /webhooks/autorizou HTTP/1.1
Host: seu-site.com.br
Content-Type: application/x-www-form-urlencoded

event=payment.authorized&payment[id]=pay_123&payment[status]=authorized
```

**Processamento:**

```php theme={null}
$payload = $request->all();
```

***

## Troubleshooting

### Webhook não está recebendo notificações

<AccordionGroup>
  <Accordion title="1. Verificar status" icon="gauge-high">
    Na Dashboard, confirme que o status está `enabled` e não `suspended`
  </Accordion>

  <Accordion title="2. Verificar eventos" icon="list-check">
    Confirme que os eventos que você espera estão selecionados na configuração
  </Accordion>

  <Accordion title="3. Testar URL" icon="link">
    Verifique se sua URL está acessível: - HTTPS válido (certificado não
    expirado) - Porta 443 aberta - Firewall permite conexões externas
  </Accordion>

  <Accordion title="4. Consultar histórico" icon="clock-rotate-left">
    Acesse o histórico de disparos na Dashboard para ver detalhes dos erros
  </Accordion>
</AccordionGroup>

### Webhook foi suspenso

Se seu webhook foi marcado como `suspended`:

<Steps>
  <Step title="Identifique o problema">
    Consulte o histórico de disparos para ver os erros Erros comuns: - Timeout
    (endpoint demorou mais de 30s) - Erro 500 (problema no seu servidor) -
    Conexão recusada (endpoint indisponível)
  </Step>

  <Step title="Corrija o problema">
    Resolva o erro identificado no seu endpoint
  </Step>

  <Step title="Reative o webhook">
    Na Dashboard, edite o webhook e altere o status para `enabled`
  </Step>
</Steps>

### Recebendo duplicatas

É normal receber o mesmo evento mais de uma vez devido ao sistema de retry automático.

**Solução:** Implemente processamento idempotente usando o ID do pagamento para evitar processar o mesmo evento múltiplas vezes.

***

## Múltiplos Webhooks

Você pode configurar múltiplos webhooks com diferentes conjuntos de eventos:

**Exemplo de uso:**

```
Webhook 1: Pagamentos
├─ payment.authorized
├─ payment.received
└─ payment.refused

Webhook 2: Estornos e Disputas
├─ payment.refunded
├─ payment.refund_denied
└─ payment.chargeback_requested

Webhook 3: Assinaturas
├─ subscription.created
├─ subscription.updated
└─ subscription.inactivated
```

Isso permite:

* Separar responsabilidades
* Enviar para sistemas diferentes
* Facilitar manutenção

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Ver Eventos" icon="bell" href="/api-reference/webhooks/events">
    Conheça todos os eventos disponíveis
  </Card>

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