Webhooks

Receba notificações automáticas quando eventos acontecem.

Configurando

cURL

curl -X POST https://api.engineapi.com.br/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/engine",
    "events": ["invoice.authorized", "invoice.rejected"]
  }'

Node.js

await fetch('https://api.engineapi.com.br/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://seusite.com/webhooks/engine',
    events: ['invoice.authorized', 'invoice.rejected'],
  }),
});

Python

resp = httpx.post('https://api.engineapi.com.br/webhooks',
    headers={'Authorization': f'Bearer {TOKEN}'},
    json={
        'url': 'https://seusite.com/webhooks/engine',
        'events': ['invoice.authorized', 'invoice.rejected'],
    },
)

Eventos

Evento	Quando dispara
invoice.authorized	Nota autorizada pela SEFAZ
invoice.rejected	Nota rejeitada
invoice.canceled	Nota cancelada
mdfe.authorized	MDFe autorizado
mdfe.closed	MDFe encerrado
nfse.authorized	NFSe autorizada
certificate.expiring_soon	Certificado vence em 30 dias
certificate.expired	Certificado expirou

Payload

{
  "event": "invoice.authorized",
  "timestamp": "2026-02-08T23:00:00.000Z",
  "data": {
    "id": "uuid-da-nota",
    "accessKey": "3526021122233300014455001...",
    "status": "AUTHORIZED",
    "type": "NFE"
  }
}

Recebendo webhooks

Node.js (Express)

import express from 'express';
const app = express();
app.use(express.json());

app.post('/webhooks/engine', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'invoice.authorized':
      console.log(`✅ NFe ${data.accessKey} autorizada`);
      // Atualizar seu banco de dados
      break;
    case 'invoice.rejected':
      console.log(`❌ NFe rejeitada: ${data.id}`);
      // Notificar usuário
      break;
    case 'certificate.expiring_soon':
      console.log(`⚠️ Certificado ${data.id} vencendo`);
      // Enviar email de alerta
      break;
  }

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

app.listen(3000, () => console.log('Webhook receiver running'));

Python (FastAPI)

from fastapi import FastAPI, Request

app = FastAPI()

@app.post('/webhooks/engine')
async def handle_webhook(request: Request):
    payload = await request.json()
    event = payload['event']
    data = payload['data']

    if event == 'invoice.authorized':
        print(f"✅ NFe {data['accessKey']} autorizada")
        # Atualizar seu banco de dados

    elif event == 'invoice.rejected':
        print(f"❌ NFe rejeitada: {data['id']}")
        # Notificar usuário

    elif event == 'certificate.expiring_soon':
        print(f"⚠️ Certificado {data['id']} vencendo")
        # Enviar email de alerta

    return {'received': True}

Boas práticas

• Responda com HTTP 200 em até 5 segundos
• Use o id para evitar duplicatas (idempotência)
• Retentativas automáticas: 1 min, 5 min, 30 min, 2h, 24h