🔔 Webhooks

POST /api/v1/webhooks/[app_code]

Recebe um webhook de uma integração externa.

Headers

X-Signature: Assinatura HMAC-SHA256 do body
X-Event-ID: ID único do evento (para idempotência)
X-Timestamp: Timestamp do evento

Request

{
  "event_type": "client.created",
  "data": {
    "id": "uuid",
    "name": "Novo Cliente"
  }
}

Response: 200 OK

{
  "received": true,
  "app": "minha-api",
  "timestamp": "2024-01-01T00:00:00Z"
}

Validação de Assinatura

A assinatura é calculada usando HMAC-SHA256:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(body))
  .digest('hex');

Idempotência

O sistema garante que eventos com o mesmo X-Event-ID não sejam processados duas vezes. Se um evento duplicado for recebido, retorna 409 Conflict.

Exemplo de Envio

curl -X POST https://api.teodosius.com/api/v1/webhooks/minha-api \
  -H "Content-Type: application/json" \
  -H "X-Signature: abc123..." \
  -H "X-Event-ID: event-123-abc" \
  -H "X-Timestamp: 2024-01-01T00:00:00Z" \
  -d '{
    "event_type": "client.created",
    "data": {
      "id": "uuid",
      "name": "Novo Cliente"
    }
  }'

Erros

401 - Assinatura inválida ou ausente
404 - Integração não encontrada
409 - Evento já processado (idempotência)