Openi DeveloperDeveloper
Guia de integração

Webhooks

Eventos enviados pelo Nexus: cadastro, payloads, assinatura, retentativas e reenvio.

O Nexus avisa sua aplicação quando ingestões e jobs terminam e quando matches são criados. Cada evento é um POST JSON para a URL que você cadastrar, assinado no padrão Standard Webhooks.

Cadastrar

Escopo admin.

curl -s -X POST https://nexus-v2.openi.com.br/v1/webhooks \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://meu-sistema.example.com/nexus",
    "description": "Conciliação ERP",
    "event_types": ["ingestion.failed", "job.completed", "job.failed", "matches.created", "matches.possible"]
  }'

A resposta (201) traz o secret (whsec_...) usado para verificar as assinaturas. Ele aparece só nesta resposta; guarde-o junto com o id do webhook.

  • A URL precisa ser https, apontar para um endereço público e não levar usuário e senha. O bloqueio de endereços privados vale também para o IP resolvido na hora da conexão.
  • Um tenant pode ter vários webhooks, cada um com seus eventos.
  • POST /v1/webhooks/{id}/test envia um evento webhook.test para conferir a integração.

Eventos

EventoQuando
ingestion.completedIngestão concluída, com as estatísticas
ingestion.failedIngestão falhou e nada foi carregado
job.completedJob concluído, com as estatísticas por etapa
job.failedJob falhou
job.cancelledJob cancelado
job.revertedMatches de um job desfeitos pelo revert
matches.createdMatches matched gravados por um job, em lotes
matches.possibleMatches possible gravados por um job, para revisão, em lotes
match.completedUm parcial foi completado e virou matched

O corpo de toda entrega tem o mesmo envelope:

{
  "type": "matches.created",
  "timestamp": "2026-10-08T14:10:02.118Z",
  "data": { ... }
}

timestamp é o momento do evento, e não da tentativa de entrega.

ingestion.completed e ingestion.failed

{
  "ingestion_id": 912,
  "dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01",
  "status": "completed",
  "stats": { "rows_total": 1500, "rows_valid": 1498, "rows_rejected": 2, "rows_inserted": 1450, "rows_duplicate": 48 }
}

Em ingestion.failed, error explica o motivo. O link do relatório de erros não vem no evento: busque-o em GET /v1/ingestions/{id}.

job.completed, job.failed e job.cancelled

{
  "job_id": "0199a3f3-1b20-7a8e-9c4d-3e5f7a9b1c22",
  "ruleset_id": "0199a3f2-9c10-7f3a-a1b2-c3d4e5f6a7b8",
  "ruleset_version": 3,
  "dry_run": false,
  "status": "completed",
  "stats": { "matched": 1284, "possible": 37, "steps": [ ... ] }
}

stats tem o mesmo formato de GET /v1/jobs/{id}. Jobs de workflow trazem workflow_id e workflow_version no lugar do ruleset. job.failed traz error. Um job cancelado ainda na fila gera job.cancelled só com job_id e status.

matches.created e matches.possible

{
  "job_id": "0199a3f3-1b20-7a8e-9c4d-3e5f7a9b1c22",
  "ruleset_id": "0199a3f2-9c10-7f3a-a1b2-c3d4e5f6a7b8",
  "matches": [
    {
      "id": 552301,
      "kind": "1:1",
      "strategy": "pair",
      "score": 96.4,
      "step": "main",
      "pass": "documento",
      "left": [{ "dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01", "record_id": 184467, "external_id": "NF-1" }],
      "right": [{ "dataset_id": "0199a3f2-8b12-7c66-92d4-5e3f7a8b9c02", "record_id": 90211, "external_id": "PIX-77812" }]
    }
  ]
}
  • Até 500 matches por evento. Um job com mais matches gera vários eventos, cada um com sua entrega.
  • step é o nome da etapa (main em jobs de um ruleset) e pass é o nome da passada de blocking, ou composite para a composição.
  • Matches compostos trazem amount_diff quando a soma não fecha exatamente.
  • matches.possible traz só os possible gravados neste job. Os que já estavam pendentes de jobs anteriores não são enviados de novo.
  • Use o external_id para localizar os registros no seu sistema, e o id do match para confirmar ou rejeitar.

match.completed

{
  "job_id": "0199a3f3-2c31-7b9f-8d5e-4f6a8b0c2d33",
  "ruleset_id": "0199a3f2-9c10-7f3a-a1b2-c3d4e5f6a7b8",
  "match_id": 548812,
  "amount_diff": 0,
  "left": [{ "dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01", "record_id": 183002, "external_id": "NF-998" }],
  "right": [ ... ]
}

right traz todas as parcelas, as que já estavam no parcial e as que o completaram.

job.reverted e webhook.test

job.reverted traz job_id e reverted (quantidade de matches desfeitos). webhook.test traz message e webhook_id, e só é enviado pelo endpoint de teste, independente de event_types.

Assinatura

Cada entrega leva três headers:

HeaderConteúdo
webhook-idId do evento (evt_...). O mesmo em todas as tentativas e reenvios: use para descartar duplicados
webhook-timestampMomento da tentativa, em segundos Unix
webhook-signaturev1,<assinatura em base64>. Durante uma rotação, duas assinaturas separadas por espaço

A assinatura é um HMAC-SHA256 de <webhook-id>.<webhook-timestamp>.<corpo>, com a chave igual aos bytes do segredo depois do prefixo whsec_, decodificados de base64. Verifique sobre o corpo exatamente como recebido, antes de qualquer parse.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret: string, headers: Headers, body: string): boolean {
  const id = headers.get('webhook-id') ?? '';
  const timestamp = headers.get('webhook-timestamp') ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest();

  return (headers.get('webhook-signature') ?? '').split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    const received = Buffer.from(signature ?? '', 'base64');
    return version === 'v1' && received.length === expected.length && timingSafeEqual(received, expected);
  });
}

As bibliotecas oficiais do Standard Webhooks (standardwebhooks em JavaScript, Python, Go, Java e outras) fazem a mesma verificação.

Entrega e retentativas

  • Responda com qualquer status 2xx em até 15 segundos para confirmar a entrega. Responda logo e processe depois.
  • Qualquer outro status, timeout ou erro de conexão gera nova tentativa em 5 s, 1 min, 5 min, 30 min, 2 h, 5 h, 10 h e 10 h, cerca de 27 horas no total. Depois disso, a entrega fica failed.
  • Redirecionamentos não são seguidos: um 3xx conta como falha.
  • As entregas são feitas em paralelo, sem garantia de ordem. Use o timestamp do envelope e o estado atual na API (GET /v1/jobs/{id}, por exemplo) quando a ordem importar.
  • A mesma entrega pode chegar mais de uma vez (reenvio, ou resposta perdida no caminho). Deduplique pelo webhook-id.

Histórico e reenvio

EndpointUso
GET /v1/webhooks/{id}/deliveriesEntregas do webhook, mais recentes primeiro, com filtro por status (pending, delivering, succeeded, failed) e event_type
GET /v1/webhook-deliveries/{id}Uma entrega com attempt_history: status HTTP, erro, duração e o início da resposta (até 1 KB) de cada tentativa
POST /v1/webhook-deliveries/{id}/redeliverEnvia de novo uma entrega succeeded ou failed, com o mesmo webhook-id. Entrega ainda em andamento devolve 409

O histórico de entregas concluídas fica disponível por 90 dias.

Desabilitar, alterar e remover

  • PATCH /v1/webhooks/{id} muda url, description e event_types, ou desabilita com enabled: false. Um webhook desabilitado continua acumulando entregas e as envia quando volta a enabled: true.
  • DELETE /v1/webhooks/{id} remove o webhook e cancela as entregas pendentes.

Rotação do segredo

curl -s -X POST https://nexus-v2.openi.com.br/v1/webhooks/<webhook_id>/rotate-secret \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"grace_hours": 24}'

A resposta traz o novo secret e previous_secret_expires_at. Durante a carência (grace_hours, de 0 a 168, padrão 24), cada entrega leva duas assinaturas: a do segredo novo e a do anterior. Aceite qualquer uma que valide, troque o segredo na sua aplicação e, depois da carência, só o novo vale. grace_hours: 0 aposenta o segredo anterior na hora.

On this page