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

# Webhooks

> Configure webhooks para receber notificações em tempo real sobre eventos importantes

## Visão geral

**Webhooks** são notificações HTTP enviadas pela Alpa Gateway API para sua aplicação quando eventos importantes ocorrem. Isso permite que você reaja em tempo real a mudanças de status, pagamentos confirmados e outros eventos sem precisar fazer polling constante.

## Pré-requisitos

Antes de começar, você precisa:

* Uma conta ativa na Alpa
* Sua API Key configurada (veja [Autenticação](/pages/authentication))
* Um endpoint HTTPS público para receber webhooks

## Funcionalidades

* **Eventos em tempo real**: Receba notificações instantâneas
* **Múltiplos eventos**: Configure webhooks para diferentes tipos de eventos
* **Retry automático**: Tentativas automáticas em caso de falha
* **Segurança**: Assinatura HMAC para validar requisições
* **Histórico**: Visualize todos os eventos enviados
* **Múltiplas URLs**: Configure diferentes endpoints para diferentes eventos

## Criando uma assinatura de webhook

### Requisição Básica

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/alpa",
    "events": ["transaction.completed", "transaction.failed"],
    "description": "Webhook para notificações de transação"
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://meusite.com.br/webhooks/alpa",
    "events": ["transaction.completed", "transaction.failed"],
    "description": "Webhook para notificações de transação",
    "status": "ACTIVE",
    "secret": "whsec_abc123...",
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}
```

<Warning>
  Guarde o `secret` em local seguro. Ele é necessário para validar a autenticidade dos webhooks recebidos e não será exibido novamente.
</Warning>

O Gateway envia webhooks usando o método **POST** para a URL configurada. Cada envio inclui o cabeçalho `X-Webhook-Signature` para validação de integridade.

### Cabeçalhos HTTP

| Cabeçalho             | Descrição                                             |
| :-------------------- | :---------------------------------------------------- |
| `Content-Type`        | Sempre `application/json`                             |
| `X-Webhook-Signature` | Assinatura HMAC-SHA256 (formato: `sha256=ASSINATURA`) |
| `X-Webhook-Event`     | Tipo do evento disparado                              |
| `X-Webhook-Delivery`  | ID único da entrega (UUID)                            |
| `User-Agent`          | `ALPA-Webhook/1.0`                                    |

### Eventos Suportados

| Evento                  | Descrição                                 |
| :---------------------- | :---------------------------------------- |
| `transaction.created`   | Uma nova transação foi gerada             |
| `transaction.updated`   | Uma transação teve seus dados atualizados |
| `transaction.completed` | Pagamento confirmado com sucesso          |
| `transaction.failed`    | Pagamento falhou ou foi recusado          |
| `payment_link.created`  | Um link de pagamento foi criado           |
| `payment_link.updated`  | Um link de pagamento foi editado          |
| `balance.updated`       | O saldo da conta foi alterado             |

### Eventos de Transação (Transaction)

* `transaction.created` - Transação criada
* `transaction.updated` - Status da transação atualizado
* `transaction.completed` - Pagamento confirmado/concluído
* `transaction.failed` - Pagamento falhou

### Eventos de Link de Pagamento

* `payment_link.created` - Link de pagamento criado
* `payment_link.updated` - Link de pagamento atualizado

## Exemplo completo

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/webhooks/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://meusite.com.br/webhooks/alpa',
    events: [
      'transaction.completed',
      'transaction.failed'
    ],
    description: 'Webhook para processar notificações de pagamento'
  })
});

const { data } = await response.json();
console.log('Webhook Secret:', data.secret);
```

## Listando assinaturas

### Listar todas as assinaturas

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/webhooks/subscriptions" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Listar eventos enviados

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/webhooks/events?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"
```

## Atualizando uma assinatura

```bash theme={null}
curl -X PUT "https://alpa-sistema-api.onrender.com/api/webhooks/subscriptions/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/alpa-v2",
    "events": ["transaction.completed", "transaction.failed"],
    "isActive": true
  }'
```

## Deletando uma assinatura

```bash theme={null}
curl -X DELETE "https://alpa-sistema-api.onrender.com/api/webhooks/subscriptions/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Validando a Assinatura

Para garantir que o webhook foi enviado pela ALPA, você deve validar o header `X-Webhook-Signature`.

1. Obtenha o corpo bruto (raw body) da requisição.
2. Gere um HMAC-SHA256 usando o corpo bruto e o seu `WEBHOOK_SECRET`.
3. Compare o resultado (em hexadecimal) com o valor recebido no header (removendo o prefixo `sha256=`).

Exemplo em Node.js:

```javascript theme={null}
const crypto = require('crypto');

function verifySignature(payload, signatureHeader, secret) {
  const [algorithm, signature] = signatureHeader.split('=');

  if (algorithm !== 'sha256') return false;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// No seu endpoint de webhook
app.post('/webhooks/alpa', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.ALPA_WEBHOOK_SECRET;

  if (!verifySignature(req.rawBody, signature, secret)) { // req.rawBody é necessário para a validação
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Processar webhook
  const event = req.body;
  console.log('Evento recebido:', event.type);

  res.status(200).json({ received: true });
});
```

### Exemplo de Validação (Python)

```python theme={null}
import hmac
import hashlib
import json

def validate_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# No seu endpoint de webhook
@app.route('/webhooks/alpa', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature', '').replace('sha256=', '')
    secret = os.getenv('ALPA_WEBHOOK_SECRET')
    
    if not validate_webhook_signature(request.json, signature, secret):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Processar webhook
    event = request.json
    print(f"Evento recebido: {event['type']}")
    
    return jsonify({'received': True}), 200
```

## Estrutura do payload

### Exemplo: transaction.completed

```json theme={null}
{
  "id": "evt_5f9d7a2b-1234-5678-90ab-cdef12345678",
  "type": "transaction.completed",
  "timestamp": "2024-03-15T10:30:00.000Z",
  "data": {
    "id": "tx_240315_a7b2c9",
    "userId": "usr_987654321",
    "value": 150.00,
    "amountCents": 15000,
    "status": "PAID",
    "paymentMethod": "PIX",
    "paymentDate": "2024-03-15T10:29:55.000Z",
    "completedAt": "2024-03-15T10:30:00.000Z"
  },
  "subscription": {
    "id": "sub_12345678",
    "url": "https://suaapiv1.com/webhooks"
  }
}
```

### Exemplo: transaction.failed

```json theme={null}
{
  "id": "evt_def456",
  "type": "transaction.failed",
  "createdAt": "2025-12-30T00:00:00.000Z",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440001",
    "amount": 199.00,
    "amountCents": 19900,
    "currency": "BRL",
    "paymentMethod": "credit_card",
    "status": "FAILED",
    "error": "Cartão recusado",
    "errorCode": "CARD_DECLINED"
  }
}
```

## 🔄 Retry e Confiabilidade

A Alpa tenta entregar webhooks automaticamente:

1. **Primeira tentativa**: Imediata
2. **Retry 1**: Após 1 minuto
3. **Retry 2**: Após 5 minutos
4. **Retry 3**: Após 15 minutos
5. **Retry 4**: Após 1 hora

<Note>
  Seu endpoint deve responder com status HTTP 200-299 para confirmar o recebimento. Respostas com erro ou timeout resultarão em retry.
</Note>

## Boas práticas

1. **Responda rapidamente**: Processe webhooks de forma assíncrona quando possível
2. **Valide a assinatura**: Sempre valide o `X-Webhook-Signature`
3. **Idempotência**: Processe eventos de forma idempotente usando o `id` do evento
4. **Logs**: Mantenha logs de todos os webhooks recebidos
5. **Testes**: Use webhooks de teste para validar sua implementação

## Testando webhooks

### Usando ngrok (Desenvolvimento Local)

```bash theme={null}
# Instale o ngrok
npm install -g ngrok

# Exponha sua aplicação local
ngrok http 3000

# Use a URL do ngrok na assinatura do webhook
# Ex: https://abc123.ngrok.io/webhooks/alpa
```

### Endpoint de Teste

```javascript theme={null}
app.post('/webhooks/alpa', express.json(), (req, res) => {
  console.log('Webhook recebido:', JSON.stringify(req.body, null, 2));
  res.status(200).json({ received: true });
});
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/api-reference/webhooks">
    Veja todos os endpoints disponíveis
  </Card>

  <Card title="Links de Pagamento" icon="link" href="/pages/guides/features/payment-links">
    Configure webhooks para links de pagamento
  </Card>
</CardGroup>