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}/testenvia um eventowebhook.testpara conferir a integração.
Eventos
| Evento | Quando |
|---|---|
ingestion.completed | Ingestão concluída, com as estatísticas |
ingestion.failed | Ingestão falhou e nada foi carregado |
job.completed | Job concluído, com as estatísticas por etapa |
job.failed | Job falhou |
job.cancelled | Job cancelado |
job.reverted | Matches de um job desfeitos pelo revert |
matches.created | Matches matched gravados por um job, em lotes |
matches.possible | Matches possible gravados por um job, para revisão, em lotes |
match.completed | Um 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 (mainem jobs de um ruleset) epassé o nome da passada de blocking, oucompositepara a composição.- Matches compostos trazem
amount_diffquando a soma não fecha exatamente. matches.possibletraz só ospossiblegravados neste job. Os que já estavam pendentes de jobs anteriores não são enviados de novo.- Use o
external_idpara localizar os registros no seu sistema, e oiddo 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:
| Header | Conteúdo |
|---|---|
webhook-id | Id do evento (evt_...). O mesmo em todas as tentativas e reenvios: use para descartar duplicados |
webhook-timestamp | Momento da tentativa, em segundos Unix |
webhook-signature | v1,<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
2xxem 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
3xxconta como falha. - As entregas são feitas em paralelo, sem garantia de ordem. Use o
timestampdo 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
| Endpoint | Uso |
|---|---|
GET /v1/webhooks/{id}/deliveries | Entregas 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}/redeliver | Envia 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}mudaurl,descriptioneevent_types, ou desabilita comenabled: false. Um webhook desabilitado continua acumulando entregas e as envia quando volta aenabled: 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.

