Webhooks

Configure webhooks para receber notificações em tempo real sobre eventos fiscais.

Eventos Disponíveis

Evento	Descrição
invoice.authorized	NFe/NFCe autorizada na SEFAZ
invoice.rejected	NFe/NFCe rejeitada
invoice.canceled	NFe/NFCe cancelada
mdfe.authorized	MDFe autorizado
mdfe.closed	MDFe encerrado
cte.authorized	CT-e autorizado
cte.canceled	CT-e cancelado
cte.cce	CC-e de CT-e registrada
boleto.registered	Boleto registrado no banco
boleto.paid	Boleto pago
boleto.canceled	Boleto cancelado
dfe.received	Documento fiscal recebido (DFe)
certificate.expiring	Certificado digital expirando

---

Obter Configuração

GET /webhooks/config

curl https://api.engineapi.com.br/webhooks/config \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta (200)

{
  "webhookUrl": "https://api.suaempresa.com/webhooks",
  "webhookSecret": "whsec_ab...xy",
  "events": ["invoice.authorized", "invoice.rejected"]
}

---

Atualizar Configuração

PATCH /webhooks/config

Body

Campo	Tipo	Descrição
webhookUrl	string (URL)	URL de destino para os webhooks
events	array	Lista de eventos para receber

curl -X PATCH https://api.engineapi.com.br/webhooks/config \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.suaempresa.com/webhooks",
    "events": ["invoice.authorized", "invoice.rejected", "boleto.paid"]
  }'

---

Enviar Webhook de Teste

POST /webhooks/test

Envia um evento de teste para validar a integração.

curl -X POST https://api.engineapi.com.br/webhooks/test \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{
  "success": true,
  "statusCode": 200,
  "body": "OK"
}

---

Regenerar Secret

POST /webhooks/secret/regenerate

Gera um novo HMAC secret. O anterior é invalidado imediatamente.

curl -X POST https://api.engineapi.com.br/webhooks/secret/regenerate \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{
  "webhookSecret": "whsec_new...xyz"
}

---

Logs de Entregas

GET /webhooks/logs?limit=50

Lista os últimos webhooks enviados com status de entrega.

curl "https://api.engineapi.com.br/webhooks/logs?limit=20" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

[
  {
    "id": "uuid",
    "eventType": "invoice.authorized",
    "status": "success",
    "attempts": 1,
    "createdAt": "2026-02-10T10:00:00Z",
    "deliveredAt": "2026-02-10T10:00:01Z"
  }
]

---

Dead Letter Queue (DLQ)

Webhooks que falharam após todas as tentativas de retry.

Listar DLQ

GET /webhooks/dlq?limit=50

curl "https://api.engineapi.com.br/webhooks/dlq" \
  -H "Authorization: Bearer SEU_TOKEN"

Reenviar webhook específico

POST /webhooks/dlq/:deliveryId/retry

curl -X POST https://api.engineapi.com.br/webhooks/dlq/uuid-delivery/retry \
  -H "Authorization: Bearer SEU_TOKEN"

Reenviar todos da DLQ

POST /webhooks/dlq/retry-all

curl -X POST https://api.engineapi.com.br/webhooks/dlq/retry-all \
  -H "Authorization: Bearer SEU_TOKEN"

Limpar DLQ

DELETE /webhooks/dlq

curl -X DELETE https://api.engineapi.com.br/webhooks/dlq \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{ "purged": 5 }

---

Verificação de Assinatura HMAC

Cada webhook inclui um header X-Webhook-Signature com assinatura HMAC-SHA256.

import crypto from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}