Webhook - Notificações de Conciliação

Dados da API

API Conciliação e Boletos
Estas APIs são utilizadas para funcionalidades adicionais, como geração e gestão de boletos:

• Produção: https://integration.enoqbank.com/enoq
• Homologação: https://api-hmg.sopague.com.br/integration
• Arquitetura: Representational State Transfer (REST)

O Webhook de conciliação permite que você receba notificações automáticas sobre mudanças de status nas transações. Este sistema oferece maior eficiência na integração, eliminando a necessidade de consultas frequentes à API.

Eventos Notificados

O sistema monitora e notifica as seguintes mudanças de status:

Status da Transação

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

Formato da Notificação

Todas as notificações seguem o seguinte formato JSON:

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

Mecanismo de Retentativas

Resiliência na Comunicação

O webhook implementa um mecanismo de retentativas em caso de falha na comunicação com o sistema do cliente.

As retentativas seguem uma política de backoff exponencial, na qual o intervalo entre as tentativas é progressivamente aumentado. Esse comportamento garante maior resiliência, permitindo que sistemas temporariamente indisponíveis ainda recebam a notificação caso retornem à operação mesmo após horas de indisponibilidade.

Dicionário de dados - Notificação

CAMPO	DESCRIÇÃO	TIPO
movementId	Identificador único da movimentação	int
nsu	Número sequencial único da transação	string
codAuth	Código de autorização	string
installmentNumber	Número da parcela	int
moment	Data e hora da mudança	datetime
type	Tipo de mudança	string
oldValue	Valor anterior	string
newValue	Novo valor	string

Resposta do Endpoint Cliente

Requisitos de Resposta

Seu endpoint deve retornar apenas um status code HTTP, não sendo necessário retornar um body na resposta.

Status codes esperados:

• 200 (OK): Para casos de sucesso no processamento da notificação
• 400 (Bad Request): Para casos de erros esperados (payload inválido, dados incorretos)
• 500 (Internal Server Error): Para casos de erros inesperados no seu sistema

Gerenciamento de Assinaturas

Registrar Webhook

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

Registra uma URL para receber notificações webhook.

Query Params Obrigatórios

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

Requisição

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

Dicionário de dados - Parâmetros

Query Parameters

CAMPO	DESCRIÇÃO	TIPO	TAMANHO	OBSERVAÇÃO
accountNumber	Número da conta do cliente	string	-	Obrigatório para todas as operações de webhook

Body Parameters

CAMPO	DESCRIÇÃO	TIPO	TAMANHO	OBSERVAÇÃO
url	URL do endpoint para receber notificações	string	-	Deve ser uma URL válida e acessível
basicAuth	Credenciais para autenticação básica	string	-	Formato: "username:password" em Base64

🟢 200

Resposta

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

Consultar Webhook

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

Consulta a URL atualmente registrada para receber notificações.

Query Params Obrigatórios

É necessário enviar o parâmetro accountNumber via query params.

🟢 200

Resposta

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

Cancelar Webhook

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

Remove a URL registrada, cancelando o recebimento de notificações.

Query Params Obrigatórios

É necessário enviar o parâmetro accountNumber via query params.

🟢 200

Resposta

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

Boas Práticas

Recomendações:

• Implemente logs detalhados para debug
• Valide o payload recebido
• Processe as notificações de forma assíncrona
• Monitore a saúde do seu endpoint
• Responda em até 30 segundos
• Mantenha o endpoint disponível 24/7