Webhook

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"
}

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

Registra uma URL para receber notificações webhook.

Requisição

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

Dicionário de dados - Parâmetros

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

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

🟢 200

Resposta

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

Cancelar Webhook

DELETE /api/webhooks/subscriptions

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

🟢 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