> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks e callbacks

> Consuma eventos de ciclo de vida do Matcher no backbone de streaming e receba callbacks de resolução para que sistemas externos mantenham as exceções em sincronia.

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](#callback-credentials). Cada campo abaixo é obrigatório. `dueAt` e `updatedAt` aceitam `null`, e `payload` pode ser um objeto vazio:

```bash cURL theme={null}
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

```json theme={null}
{
  "status": "accepted"
}
```

> [!TIP]
>
> Referência da API: [Processar callback](https://docs.lerian.studio/pt/reference/products/matcher/process-exception-callback.md)

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. |

> [!TIP]
>
> Referência da API:
>
> * [Emitir credencial de callback](https://docs.lerian.studio/pt/reference/products/matcher/mint-callback-credential.md)
> * [Listar credenciais de callback](https://docs.lerian.studio/pt/reference/products/matcher/list-callback-credentials.md)
> * [Rotacionar credencial de callback](https://docs.lerian.studio/pt/reference/products/matcher/rotate-callback-credential.md)
> * [Revogar credencial de callback](https://docs.lerian.studio/pt/reference/products/matcher/revoke-callback-credential.md)

### 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.

```bash cURL theme={null}
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. |

> [!WARNING]
>
> 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

```bash cURL theme={null}
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

```bash cURL theme={null}
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

***

> [card] [Roteamento de exceções](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-exception-routing.md)
>
> Configure regras que roteiam exceções.

> [card] [Fontes externas](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-external-sources.md)
>
> Configure fontes de dados. Entre elas, só as conexões com agregadores recebem webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.