🔔 Webhooks

Recebendo Webhooks

A API pode receber webhooks de integrações externas através do endpoint:

POST /api/v1/webhooks/[app_code]

Validação de Assinatura

Todos os webhooks devem incluir uma assinatura HMAC-SHA256 no header X-Signature:

const crypto = require('crypto');
const secret = 'seu-secret-da-integracao';
const body = JSON.stringify(payload);

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

Idempotência

Para garantir que eventos não sejam processados duas vezes, inclua um X-Event-ID único no header:

X-Event-ID: event-123-abc-456

Se o mesmo X-Event-ID for recebido novamente, a API retornará 409 Conflict.

Headers Requeridos

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

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"
    }
  }'