Registrar Webhook

POST/api/webhooks/subscriptions?accountNumber={accountNumber}

Registra uma URL para receber notificações automáticas sobre mudanças de status nas transações de conciliação.

É necessário enviar o parâmetro accountNumber via query params junto com o corpo da requisição.

Exemplo de requisição

{
  "url": "https://meusite.com.br/webhook/notificacoes",
  "basicAuth": "dXNlcjpwYXNzd29yZA=="
}

Dicionário de dados - Query Parameters

Dicionário de dados - Body

Exemplo de resposta

{
  "url": "https://meusite.com.br/webhook/notificacoes"
}

Formato da Notificação Recebida

Todas as notificações enviadas ao seu endpoint seguem o formato:

{
  "movementId": 0,
  "nsu": "string",
  "codAuth": "string",
  "installmentNumber": 0,
  "moment": "datetime",
  "type": "string",
  "oldValue": "string",
  "newValue": "string"
}

Eventos Notificados

Autorizada: Transação aprovada
Cancelada: Transação cancelada
Bloqueada: Transação bloqueada temporariamente
Paga: Pagamento efetivado com sucesso

Mecanismo de Retentativas

O webhook implementa retentativas com política de backoff exponencial em caso de falha na comunicação. Seu endpoint deve retornar apenas um status HTTP (sem body):

200: Sucesso no processamento
400: Erro esperado (payload inválido)
500: Erro inesperado no seu sistema

Erros

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Observado em homologação

Requisição sem o header Authorization. A camada de autenticação pode rejeitar a chamada antes de resolver a rota ou validar os dados.

HTTP/1.1 401 Unauthorized

A resposta não possui corpo. Não há campos JSON para interpretar neste cenário.