Webhooks e callbacks

Este guia cobre os eventos que o Matcher publica e os callbacks de entrada que sistemas externos enviam ao Matcher.

Visão geral

Eventos de saída: o Matcher publica seu catálogo de eventos de ciclo de vida no backbone de streaming da plataforma. Esses eventos chegam até você como stream, não como webhooks HTTP.
Callbacks de entrada: sistemas externos, como uma ferramenta de chamados, avisam o Matcher quando agem sobre uma exceção. Então o Matcher atualiza o status da exceção.

Eventos de saída

O Matcher emite eventos quando ações relevantes acontecem no processo de conciliação e os publica no backbone de streaming. Cada evento segue seu próprio schema no stream de eventos.

Eventos disponíveis

As tabelas abaixo listam o catálogo de eventos por domínio. 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 mudaram	Rastreio de mudanças de configuração
`reconciliation_source.created`	Fonte criada dentro de um contexto	Entrada de nova fonte
`match_rule.created`	Regra de correspondência criada	Auditoria de mudanças de regra
`match_rule.reordered`	Prioridades de regras reordenadas	Auditoria de mudanças de regra

Discovery

Evento	Gatilho	Uso típico
`fetcher_connection.synced`	Conexão e snapshot do schema sincronizados	Monitoramento da descoberta
`fetcher_connection.unreachable`	Conexão marcada como inalcançável	Alerta de conectividade
`extraction_request.created`	Pedido de extração criado	Monitoramento de extração
`extraction_request.submitted`	Extração aceita pelo motor de extração	Monitoramento de extração
`extraction_request.completed`	Extração concluída e entregue à ingestão	Prontidão dos dados
`extraction_request.failed`	Extração falhou	Alerta de erro

Ingestão

Evento	Gatilho	Uso típico
`ingestion.completed`	Importação de arquivo terminou	Monitoramento do pipeline de dados
`ingestion.failed`	Importação de arquivo falhou	Alerta de erro
`transaction.ignored`	Transação não conciliada marcada como ignorada	Trilha de auditoria

Correspondência

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

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 despachada para um sistema de destino	Trilha de auditoria
`exception.callback_processed`	Callback externo processado	Sincronização de status
`exception.force_match_resolved`	Exceção resolvida por correspondência forçada	Workflows de aprovação
`exception.adjust_entry_resolved`	Exceção resolvida por 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	Acompanhamento 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	Acompanhamento 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 começou	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 na fila	Monitoramento de exportações
`export_job.succeeded`	Job de exportação concluído	Download disponível
`export_job.failed`	Job de exportação falhou	Alerta de erro
`export_job.expired`	Artefato de exportação expirou	Ciclo de vida da exportação

Callbacks de entrada

Sistemas externos enviam callbacks ao Matcher para atualizar o status da exceção depois do processamento. O endpoint de callback aceita atualizações de status, notas de resolução e mudanças de responsável de qualquer sistema externo.

Processar um callback

O header X-Callback-Token autentica o endpoint de callback. Um JWT de operador não o autentica. O header carrega um token opaco da superfície de credenciais de callback. Cada campo abaixo é obrigatório. 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: 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 informar qualquer identificador de sistema. Omitir qualquer um dos nove campos obrigatórios retorna 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. O header X-Idempotency é obrigatório. O Matcher lê a chave de idempotência apenas desse header. Uma requisição que carrega uma chave apenas em X-Idempotency-Key ou Idempotency-Key é recusada com 400 (MTCH-0015), e nada é processado. O Matcher deduplica um callback pelo sistema externo, pela exceção e pela chave em conjunto. A mesma chave em outra exceção ou vinda de outro sistema externo é um novo callback.

Status do callback

status move a exceção para ASSIGNED ou RESOLVED. O Matcher lê o valor sem diferenciar maiúsculas de minúsculas.
Para mover a exceção para ASSIGNED, envie um assignee não vazio.
Quando status é o status atual da exceção, o Matcher mantém o status e atualiza assignee e dueAt se você os enviar.

Recusas do callback

Status	Código	Significado
`400`	`MTCH-0015`	A chave chegou apenas em `X-Idempotency-Key` ou `Idempotency-Key`.
`400`	`MTCH-0001`	O callback não é válido. Por exemplo, o valor de `X-Idempotency` não tem de 1 a 128 letras, dígitos, `:`, `_` ou `-`, ou um callback `ASSIGNED` não tem `assignee`.
`409`	`MTCH-0504`	Outro callback com a mesma chave ainda está em processamento. Envie a requisição de novo mais tarde.
`409`	`MTCH-0505`	O Matcher não consegue confirmar o estado de um callback anterior com a mesma chave. Envie a requisição de novo mais tarde.
`429`	`MTCH-0506`	O sistema externo enviou mais callbacks do que seu limite de taxa permite. Envie a requisição de novo mais tarde.

Um token de callback desconhecido ou revogado recebe 404. Quando o Matcher não consegue verificar o token, ele responde 503.

Nova tentativa automática para callbacks que falharam

Se um callback anterior com a mesma chave de idempotência falhou durante o processamento, o Matcher tenta automaticamente readquirir o lock de idempotência e reprocessar o callback. Você não precisa gerar uma nova chave de idempotência ao repetir um callback que falhou. Reenvie a mesma requisição e o Matcher cuida da recuperação. Esse comportamento de nova tentativa vale apenas para callbacks com estado interno failed. O Matcher continua deduplicando callbacks que terminaram com sucesso.

Credenciais de callback

Um token bearer opaco autentica os callbacks de entrada. O sistema externo envia esse token no header X-Callback-Token. Você emite, lista, rotaciona e revoga essas credenciais de callback por uma superfície CRUD dedicada em /v1/exceptions/callbacks/credentials. Cada credencial pertence ao tenant de quem chama. O Matcher guarda apenas o hash SHA-256 do token no servidor. As respostas de emissão e de rotação retornam o token bruto exatamente uma vez.

Ação	Método e caminho	Observações
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 de forma atômica uma credencial ativa por outra 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 a credencial em definitivo (`204`); auditado em modo append-only.

Referência da API:

Emitir uma credencial

A requisição precisa de um corpo JSON. Envie {} se você não definir um rótulo. O campo externalSystem é opcional. Informe-o como um rótulo legível pelo operador para o 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, mostrado uma vez. Configure-o como valor do header `X-Callback-Token` no sistema externo.
`credentialId`	Id substituto da credencial emitida (usado para rotacionar e revogar).
`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 fora do Matcher; o marcador `{exceptionId}` é preenchido a cada callback.

Apenas as respostas de emissão e de rotação mostram o token bruto. Guarde-o com segurança ao recebê-lo. Você não pode recuperá-lo de novo. Se perder ou vazar o token, 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 (201, novo token bruto) e revoga a credencial anterior na mesma transação. Callbacks que ainda enviam o token antigo falham, então atualize o sistema externo com o novo token imediatamente.

Revogar uma credencial

cURL

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

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

Próximos passos

Roteamento de exceções

Configure regras que roteiam exceções.

Fontes externas

Configure fontes de dados. Entre elas, só as conexões com agregadores recebem webhooks.

Visão geral

Guias

Console

Operações

Webhooks e callbacks

Visão geral

Eventos de saída

Eventos disponíveis

Callbacks de entrada

Processar um callback

Resposta

Status do callback

Recusas do callback

Nova tentativa automática para callbacks que falharam

Credenciais de callback

Emitir uma credencial

Rotacionar uma credencial

Revogar uma credencial

Próximos passos

Roteamento de exceções

Fontes externas

​Visão geral

​Eventos de saída

​Eventos disponíveis

​Callbacks de entrada

​Processar um callback

​Resposta

​Status do callback

​Recusas do callback

​Nova tentativa automática para callbacks que falharam

​Credenciais de callback

​Emitir uma credencial

​Rotacionar uma credencial

​Revogar uma credencial

​Próximos passos

Roteamento de exceções

Fontes externas

Visão geral

Eventos de saída

Eventos disponíveis

Callbacks de entrada

Processar um callback

Resposta

Status do callback

Recusas do callback

Nova tentativa automática para callbacks que falharam

Credenciais de callback

Emitir uma credencial

Rotacionar uma credencial

Revogar uma credencial

Próximos passos