Os webhooks são usados para notificar seu sistema automaticamente sobre eventos significativos que ocorrem dentro da plataforma. Cada evento é enviado como um POST HTTP para a URL de webhook que você configurou previamente. Os dados são enviados no corpo da requisição como um objeto JSON.

​
Configurando Webhooks

Os usuários podem fornecer um callbackUrl em qualquer operação que suporte notificações, como a geração de um Pix, realização de transferências, entre outros. Este URL será usado exclusivamente para notificar o resultado da operação específica solicitada.

​
Segurança dos Webhooks

Para garantir que os webhooks sejam autênticos e não tenham sido modificados durante a transmissão, cada webhook incluirá um campo hash. Este hash é gerado usando um algoritmo de hash HMAC com uma chave secreta compartilhada entre você e a plataforma.

​
Gerando o Hash de Confirmação

O hash é gerado da seguinte forma:

  1. Concatene o corpo da mensagem JSON (excluindo o campo hash) como uma string.
  2. Aplique a função de hash HMAC usando SHA-256, juntamente com a chave secreta compartilhada.
  3. Converta o resultado em uma string hexadecimal.

​
Validando o Hash de Confirmação

Os desenvolvedores devem verificar este hash para confirmar a integridade e a autenticidade do webhook.

​
Eventos de Webhook

Quando o evento associado à requisição ocorrer, como o pagamento de um Pix sendo completado ou uma transferência sendo realizada, o sistema enviará uma notificação para o callbackUrl fornecido. A notificação incluirá detalhes sobre o evento:

​
Formato do Objeto de Webhook

Quando um evento ocorre, o sistema enviará uma requisição POST para a URL do webhook configurada com o seguinte formato de objeto JSON:

{
	"event": "received_pix",
	"hash": "c2f7a4a98awjd982198djasdimi82a9usdh",
	"data": {
		"identifier": "123456789",
		"amount": 100.5,
		"timestamp": "2021-12-01T12:00:00Z"
	}
}

​
Descrição dos Campos

  • identifier: Identificador único da transação no seu sistema.
  • amount: Valor do pagamento realizado.
  • timestamp: Data e hora em que o pagamento foi processado.

​
Evento: failed_pix

Notifica que uma tentativa de pagamento via Pix falhou.

​
Estrutura do Payload

{
	"event": "failed_pix",
	"hash": "c2f7a4a98awjd982198djasdimi82a9usdh",
	"data": {
		"identifier": "tx124",
		"amount": 200.0,
		"timestamp": "2022-03-01T12:15:00Z",
		"reason": "Saldo insuficiente"
	}
}

​
Descrição dos Campos

  • identifier: Identificador único da transação no seu sistema.
  • amount: Valor do pagamento que falhou.
  • timestamp: Data e hora em que o pagamento foi processado.
  • reason: Motivo pelo qual o pagamento falhou.

​
Evento: received_pix

Notifica que um pagamento via Pix foi recebido com sucesso.

​
Estrutura do Payload

{
	"event": "received_pix",
	"hash": "c2f7a4a98awjd982198djasdimi82a9usdh",
	"data": {
		"identifier": "tx125",
		"amount": 150.0,
		"timestamp": "2022-03-01T12:20:00Z"
	}
}

​
Descrição dos Campos

  • identifier: Identificador único da transação no seu sistema.
  • amount: Valor do pagamento recebido.
  • timestamp: Data e hora em que o pagamento foi processado.

​
Segurança e práticas recomendadas

Para garantir a segurança dos seus webhooks, recomendamos que você siga as práticas recomendadas a seguir:

  • Use HTTPS: Certifique-se de que a URL do webhook comece com https:// para garantir que os dados sejam transmitidos de forma segura.
  • Use autenticação: Adicione um cabeçalho de autenticação à sua requisição para garantir que apenas o GatewayFy possa enviar webhooks para o seu sistema.
  • Use tokens de segurança: Adicione um token de segurança à URL do webhook para garantir que apenas o GatewayFy possa enviar webhooks para o seu sistema.

​
Monitorando e Validando Callbacks

É importante monitorar as respostas dos callbacks para assegurar que foram recebidos corretamente. O sistema deve tratar as falhas de envio e reenviar a notificação se necessário ou registrar erros para análise futura.

Responder adequadamente a cada tipo de evento ajuda a manter sua aplicação sincronizada com o estado atual da plataforma e permite tomar ações baseadas em eventos reais e verificados.

​
Resposta aos Webhooks

Após processar um webhook, o endpoint seu sistema deve retornar um status HTTP 2XX para indicar que o webhook foi recebido e processado com sucesso. Outros códigos de status podem indicar que o webhook não foi aceito e pode ser necessário reenviar a notificação.

​
Logs e Troubleshooting

Mantenha registros detalhados das requisições de webhook e das respostas recebidas para facilitar o troubleshooting e a análise de problemas. Isso é crucial para garantir a eficiência e confiabilidade do sistema de notificações.

Tratamento de errosPing