Webhooks e callbacks

Webhooks permitem comunicação em tempo real entre o Matcher e sistemas externos. Este guia aborda notificações de eventos de saída e callbacks de resolução de entrada.

Visão geral

O Matcher suporta comunicação bidirecional via webhook, mantendo suas ferramentas operacionais sincronizadas com cada evento de conciliação em tempo real. Isso reduz a intervenção manual, ajuda a manter o cumprimento de SLAs e garante uma trilha de auditoria contínua em todos os sistemas conectados.

Webhooks de saída: o roteamento de exceções envia exceções para destinos externos — JIRA, ServiceNow ou um endpoint HTTP de webhook que você configura
Callbacks de entrada: sistemas externos notificam o Matcher quando ações são tomadas

Quando uma exceção é roteada para um destino de webhook, o Matcher entrega uma requisição HTTP assinada ao seu endpoint. Sistemas externos como JIRA ou ServiceNow podem então enviar callbacks para atualizar o status da exceção ou fechar itens automaticamente. Esse fluxo bidirecional mantém suas ferramentas sincronizadas sem intervenção manual. Além do envio de exceções, o Matcher publica seu catálogo completo de eventos de ciclo de vida no backbone de streaming da plataforma — esses eventos são consumidos como um stream, não entregues como webhooks HTTP.

Matcher Webhooks Callbacks — Fluxo bidirecional entre o Matcher e sistemas externos.

Eventos de saída

O Matcher emite eventos quando ações significativas ocorrem no processo de conciliação. O catálogo abaixo é publicado no backbone de streaming; eventos de exceção também chegam a endpoints HTTP de webhook por meio do roteamento de exceções.

Eventos disponíveis

O catálogo de eventos do Matcher é definido de forma centralizada. Os eventos mais comumente consumidos estão agrupados por domínio abaixo. Configuração

Evento	Gatilho	Uso típico
`reconciliation_context.created`	Contexto de conciliação criado	Sincronização de provisionamento
`reconciliation_context.updated`	Metadados ou status do contexto alterados	Rastreamento de mudanças de configuração
`reconciliation_context.deleted`	Contexto excluído	Desmontagem downstream
`reconciliation_source.created`	Fonte criada dentro de um contexto	Onboarding de fontes
`match_rule.created`	Regra de correspondência criada	Auditoria de mudanças de regras
`match_rule.reordered`	Prioridades de regras reordenadas	Auditoria de mudanças de regras

Descoberta (Fetcher)

Evento	Gatilho	Uso típico
`fetcher_connection.synced`	Snapshot de conexão e esquema sincronizado	Monitoramento de descoberta
`fetcher_connection.unreachable`	Conexão marcada como inacessível	Alertas de conectividade
`extraction_request.created`	Solicitação de extração criada	Monitoramento de extração
`extraction_request.submitted`	Extração aceita pelo Fetcher	Monitoramento de extração
`extraction_request.completed`	Extração concluída com artefato	Disponibilidade de dados
`extraction_request.failed`	Extração falhou	Alertas de erro
`extraction_request.cancelled`	Extração cancelada	Monitoramento do pipeline
`extraction_request.bridged`	Extração vinculada a um job de ingestão	Monitoramento do pipeline
`extraction_request.bridge_failed`	Ponte para a ingestão falhou	Alertas de erro

Ingestão

Evento	Gatilho	Uso típico
`ingestion.completed`	Importação de arquivo concluída	Monitoramento de pipeline de dados
`ingestion.failed`	Importação de arquivo falhou	Alertas de erro
`transaction.ignored`	Transação não correspondida marcada como ignorada	Trilha de auditoria

Correspondência

Evento	Gatilho	Uso típico
`match_run.completed`	Job de correspondência concluído	Monitoramento de jobs, relatórios
`match_run.failed`	Job de correspondência falhou	Alertas de erro
`match_group.confirmed`	Grupo de correspondência confirmado	Atualizações downstream
`match_group.unmatched`	Correspondência confirmada revertida	Rastreamento de correções
`transaction.matched`	Transação marcada como correspondida	Registro de auditoria
`transaction.pending_review`	Candidato não automático precisa de revisão	Gatilhos de fila de revisão
`fee_variance.created`	Variação de taxa detectada	Investigação de taxas

Exceções e disputas

Evento	Gatilho	Uso típico
`exception.assigned`	Exceção atribuída a um responsável	Notificação de usuário
`exception.resolved`	Exceção resolvida	Sincronização de status
`exception.dispatched`	Exceção enviada para um destino externo	Criação de tickets
`exception.callback_processed`	Callback externo processado	Sincronização de status
`exception.force_match_resolved`	Exceção resolvida via correspondência forçada	Fluxos de aprovação
`exception.adjust_entry_resolved`	Exceção resolvida via lançamento de ajuste	Trilha de auditoria
`exception_comment.added`	Comentário adicionado a uma exceção	Sincronização de colaboração
`exception_comment.deleted`	Comentário de exceção excluído	Sincronização de colaboração
`dispute.opened`	Disputa aberta para uma exceção	Rastreamento de disputas
`dispute.won`	Disputa encerrada como ganha	Sincronização de status
`dispute.lost`	Disputa encerrada como perdida	Sincronização de status
`evidence.submitted`	Evidência enviada a uma disputa	Rastreamento de disputas

Governança e relatórios

Evento	Gatilho	Uso típico
`audit_log.created`	Entrada de log de auditoria adicionada	Monitoramento de conformidade
`archive_metadata.created`	Ciclo de vida de arquivamento iniciado	Monitoramento de arquivamento
`archive.uploaded`	Objeto de arquivo enviado	Monitoramento de arquivamento
`archive.completed`	Arquivo verificado e concluído	Monitoramento de arquivamento
`actor.pseudonymized`	Mapeamento de ator pseudonimizado	Monitoramento de conformidade
`export_job.created`	Job de exportação enfileirado	Monitoramento de exportação
`export_job.succeeded`	Job de exportação concluído	Disponibilidade de download
`export_job.failed`	Job de exportação falhou	Alertas de erro
`export_job.expired`	Artefato de exportação expirado	Ciclo de vida de exportação

Payload de entrega de webhook

Os envios de exceções para um destino de webhook carregam um payload consistente — eventId, eventType, timestamp, o snapshot da exceção sob data e as informações de roteamento/rastreamento sob metadata:

{
  "eventId": "0e8f1c2a-5b6d-4f3e-9a7b-1c2d3e4f5a6b",
  "eventType": "exception.dispatched",
  "timestamp": "2026-01-20T10:30:00Z",
  "data": {
    "exceptionId": "9b2f4e6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "transactionId": "7a1b3c5d-9e8f-4a2b-b6c7-d8e9f0a1b2c3",
    "severity": "HIGH",
    "status": "PENDING",
    "amount": "15000.00",
    "currency": "USD",
    "reason": "No matching ledger entry found",
    "sourceType": "LEFT",
    "createdAt": "2026-01-20T10:29:15Z",
    "dueAt": "2026-01-23T10:29:15Z"
  },
  "metadata": {
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "target": "WEBHOOK",
    "queue": "ops-review",
    "ruleName": "high-value-unmatched",
    "assignee": "ops-team"
  }
}

data.dueAt e os campos de metadata traceId, queue, ruleName e assignee são omitidos quando não definidos. Os eventos do catálogo de streaming (as tabelas acima) seguem seus próprios esquemas por evento no stream de eventos e não são entregues neste formato HTTP.

Callbacks de entrada

Sistemas externos enviam callbacks para o Matcher para atualizar o status das exceções após o processamento. O endpoint de callback aceita atualizações de status, notas de resolução e mudanças de atribuição de qualquer sistema externo.

Processar um callback

O endpoint de callback é autenticado pelo cabeçalho X-Callback-Token — um token opaco emitido pela superfície de credenciais de callback —, não por um JWT de operador. Todos os campos mostrados abaixo são obrigatórios; dueAt e updatedAt aceitam null, e payload pode ser um objeto vazio:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/callback" \
 -H "X-Callback-Token: ***" \
 -H "X-Idempotency-Key: callback-jira-1234" \
 -H "Content-Type: application/json" \
 -d '{
   "callbackType": "status_update",
   "externalSystem": "JIRA",
   "externalIssueId": "RECON-1234",
   "status": "RESOLVED",
   "resolutionNotes": "Verified: amount difference is expected bank wire fee",
   "assignee": "john.doe@company.com",
   "dueAt": null,
   "updatedAt": "2026-01-20T14:30:00Z",
   "payload": {}
 }'

O campo externalSystem identifica o sistema externo que processou a exceção. Valores comuns incluem "JIRA", "SERVICENOW" ou "WEBHOOK", mas os callbacks podem reportar qualquer identificador de sistema. Omitir qualquer um dos nove campos obrigatórios retorna um 422.

Resposta

{
  "status": "accepted"
}

Referência da API: Processar callback

Quando o Matcher processa um callback, ele atualiza o status da exceção e registra a resolução na trilha de auditoria. Use o header X-Idempotency-Key para prevenir processamento duplicado.

Retry automático para callbacks com falha

Se um callback anterior para a mesma chave de idempotência falhou durante o processamento, o Matcher tenta automaticamente readquirir o bloqueio de idempotência e reprocessar o callback. Isso significa que você não precisa gerar uma nova chave de idempotência ao retentar um callback com falha: basta reenviar a mesma requisição e o Matcher cuida da recuperação. O comportamento de retry se aplica apenas a callbacks que foram marcados como failed internamente. Callbacks concluídos com sucesso continuam sendo deduplicados normalmente.

Credenciais de callback

Callbacks de entrada são autenticados com um token bearer opaco que o sistema externo envia no header X-Callback-Token. Essas credenciais de callback são emitidas, listadas, rotacionadas e revogadas através de uma superfície CRUD dedicada em /v1/exceptions/callbacks/credentials. Cada credencial é vinculada ao tenant do chamador, e apenas o hash SHA-256 do token é armazenado no servidor — o token bruto é retornado exatamente uma vez no momento da emissão/rotação.

Ação	Método e caminho	Notas
Emitir credencial	`POST /v1/exceptions/callbacks/credentials`	Cria uma credencial e retorna o token bruto uma vez (`201`).
Listar credenciais	`GET /v1/exceptions/callbacks/credentials`	Lista os metadados das credenciais do tenant (nunca os tokens brutos).
Rotacionar credencial	`POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate`	Substitui atomicamente uma credencial ativa por uma recém-emitida (mesmo rótulo) e retorna o novo token bruto uma vez; a antiga é revogada na mesma transação.
Revogar credencial	`DELETE /v1/exceptions/callbacks/credentials/{credentialId}`	Revoga terminalmente uma credencial (`204`); auditada em modo somente-anexação.

Referência da API: Emitir credencial de callback | Listar credenciais de callback | Rotacionar credencial de callback | Revogar credencial de callback

Emitir uma credencial

O corpo da requisição é opcional; forneça externalSystem como um rótulo legível para operadores do sistema que este token autentica.

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "externalSystem": "stripe" }'

A resposta 201 (CredentialSecretResponse) retorna:

Campo	Descrição
`token`	Token bearer bruto, exposto uma vez. Configure-o como o valor do header `X-Callback-Token` no sistema externo.
`credentialId`	ID substituto da credencial emitida (usado para rotação/revogação).
`createdAt`	Momento da emissão (RFC 3339, UTC).
`externalSystem`	O rótulo devolvido para confirmação.
`webhookUrlHint`	Formato informativo da URL de callback de entrada para configurar externamente; o placeholder `{exceptionId}` é preenchido por callback.

O token bruto é exibido apenas nas respostas de emissão e rotação. Armazene-o com segurança ao recebê-lo — ele não pode ser recuperado novamente. Se for perdido ou vazado, rotacione ou revogue a credencial.

Rotacionar uma credencial

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}/rotate" \
 -H "Authorization: Bearer $TOKEN"

A rotação retorna um novo CredentialSecretResponse (novo token bruto) e revoga a credencial anterior atomicamente, de modo que os chamadores externos não sofram interrupção ao trocar o token.

Revogar uma credencial

cURL

curl -X DELETE "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}" \
 -H "Authorization: Bearer $TOKEN"

A revogação é terminal: a credencial não pode mais autenticar callbacks de entrada.

Segurança de webhooks

Verificação de assinatura

Quando um segredo compartilhado de webhook está configurado, o Matcher assina cada entrega com um HMAC-SHA256 sobre o corpo bruto da requisição e o envia no header X-Signature-256, formatado como sha256=<hex-digest>:

X-Signature-256: sha256=abc123...

Cada entrega também inclui um header X-Idempotency-Key para que os receptores possam deduplicar retentativas. Processo de verificação:

Calcule o HMAC-SHA256 do corpo bruto da requisição usando o segredo compartilhado do webhook
Adicione o prefixo sha256= ao hex digest
Compare (em tempo constante) com o header X-Signature-256

Exemplo (Node.js):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
 const expectedSignature = crypto
 .createHmac('sha256', secret)
 .update(payload)
 .digest('hex');

 return `sha256=${expectedSignature}` === signature;
}

Exemplo (Python):

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
 expected = hmac.new(
 secret.encode(),
 payload,
 hashlib.sha256
 ).hexdigest()
 return f"sha256={expected}" == signature

Postura de rede

O Matcher é implantado na sua própria infraestrutura, então as entregas de webhook se originam no egress do seu deployment — não há uma faixa fixa de IPs da Lerian para permitir. Sirva os endpoints de webhook por HTTPS com um certificado válido. Como proteção contra SSRF, o Matcher se recusa a entregar para endereços IP privados ou de loopback, a menos que o deployment os permita explicitamente (apenas desenvolvimento).

Lógica de retry

Entregas de webhook com falha são retentadas com backoff exponencial.

Política de retry padrão

Uma entrega com falha é retentada até 3 vezes por padrão. Os atrasos seguem backoff exponencial a partir de uma base de 1 segundo, com jitter adicionado para distribuir as retentativas — então o espaçamento exato varia de uma tentativa para outra, em vez de seguir uma escala fixa.

Condições de retry

Retries ocorrem para:

Respostas HTTP 429
Respostas HTTP 5xx
Erros de transporte (falhas de conexão, timeouts)

Sem retry para:

Outras respostas HTTP 4xx

Melhores práticas

Verifique assinaturas de webhook

Sempre verifique a assinatura HMAC antes de processar payloads de webhook. Isso previne requisições falsificadas.

Responda rapidamente

Retorne uma resposta 2xx dentro de 5 segundos. Processe o evento de forma assíncrona se necessário.

Trate duplicatas de forma idempotente

Entregas podem chegar mais de uma vez. Deduplique pelo cabeçalho X-Idempotency-Key ou pelo eventId do payload.

Monitore a saúde das entregas

Configure alertas para taxas de falha de webhook. Investigue falhas persistentes prontamente.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Webhooks e callbacks

Visão geral

Eventos de saída

Eventos disponíveis

Payload de entrega de webhook

Callbacks de entrada

Processar um callback

Resposta

Retry automático para callbacks com falha

Credenciais de callback

Emitir uma credencial

Rotacionar uma credencial

Revogar uma credencial

Segurança de webhooks

Verificação de assinatura

Postura de rede

Lógica de retry

Política de retry padrão

Condições de retry

Melhores práticas

Próximos passos

Roteamento de exceções

Fontes externas

​Visão geral

​Eventos de saída

​Eventos disponíveis

​Payload de entrega de webhook

​Callbacks de entrada

​Processar um callback

​Resposta

​Retry automático para callbacks com falha

​Credenciais de callback

​Emitir uma credencial

​Rotacionar uma credencial

​Revogar uma credencial

​Segurança de webhooks

​Verificação de assinatura

​Postura de rede

​Lógica de retry

​Política de retry padrão

​Condições de retry

​Melhores práticas

​Próximos passos

Roteamento de exceções

Fontes externas

Visão geral

Eventos de saída

Eventos disponíveis

Payload de entrega de webhook

Callbacks de entrada

Processar um callback

Resposta

Retry automático para callbacks com falha

Credenciais de callback

Emitir uma credencial

Rotacionar uma credencial

Revogar uma credencial

Segurança de webhooks

Verificação de assinatura

Postura de rede

Lógica de retry

Política de retry padrão

Condições de retry

Melhores práticas

Próximos passos