Configurar webhooks

Vamos te mostrar como usar nossos webhooks para receber notificações em tempo real.

Na Pomelo usamos webhooks para informar sobre os principais eventos que afetam sua operação. Cada vez que esses eventos acontecem, fazemos uma solicitação `POST` a um endpoint HTTPS em seu servidor usando um objeto JSON com a informação.

Como configurar um webhook

Passo 1: Criar seu endpoint

Você deve criar um endpoint em seu servidor que cumpra estes requisitos:

• Receber tráfego por HTTPS
• Receber um objeto JSON no corpo da solicitação

Passo 2: Reconhecer nossos IPs

Sempre nos comunicamos desde IPs específicos próprios. Recomendamos que só aceite solicitações de algum de nossos IPs e que rejeite qualquer outro endereço.

• Ambiente de Testing/Staging:
  34.226.254.178
44.198.3.59
34.223.185.46
100.20.205.117
  

• Ambiente de Produção:
  34.206.159.176
52.0.20.124
35.84.78.117
52.43.46.111
  

Passo 3: Validar nossa assinatura

Como medida de segurança, assinamos as solicitações que enviamos usando hmac-sha256 para que você possa ter certeza de que são nossas. Durante o processo de onboarding, vamos compartilhar um `api-key` e `api-secret` tal como explicado em Intercâmbio de chaves.

Em cada solicitação enviamos headers HTTP que permitirão validar que a assinatura seja correta:

• x-api-key: permitirá identificar qual `api-secret` usar (no caso de que tenham sido configurados múltiplos pares de `api-key` e `api-secret`).

• x-signature: contém a assinatura digital (timestamp + endpoint + body) que você terá que validar para assegurar a integridade da solicitação. A geramos usando o `api-secret` que compartilhamos previamente. Se a assinatura não coincidir, você deverá rejeitar a solicitação.

• x-timestamp: contém o momento em que foi assinado o pedido em formato unix-epoch para que você possa regenerar a assinatura e verificar que é válida. No caso de Autorizar transação, além disso permitirá validar que a assinatura não expirou (expiram após 1 minuto).

• x-endpoint: é o endpoint ao qual se realiza a solicitação e que utilizamos para gerar a assinatura. Você deve usar este header para regenerar a assinatura a validar, compará-lo com o endpoint de seu serviço e verificar que coincidem.

A seguir mostramos um exemplo de como verificar a validade da assinatura:

Passo 4: Assinatura de resposta (somente para autorizar transações)

Para autorizar transações, também pediremos que você assine a resposta.

Os headers HTTP que você deverá enviar são:

• x-api-key: este header permitirá identificar qual api-secret você tem que usar no caso de que tenham sido configurados múltiplos pares de api-key e api-secret.

• x-signature: este header contém a assinatura digital (timestamp + endpoint + body) que você deverá verificar para assegurar a integridade do request. Se a assinatura não coincidir, você deverá rejeitar o pedido.

• x-timestamp: este header contém o momento em que foi assinado o pedido em formato unix-epoch para que você possa corroborar que a assinatura não expirou.

• x-endpoint: o endpoint ao qual se realiza o pedido e que foi usado para gerar a assinatura. Use este header para regenerar a assinatura a validar, compará-lo com o endpoint de seu serviço e verificar que coincidem.

Passo 5: Resposta para casos que não precisem assinatura

Esperamos uma resposta do tipo 2XX para nos assegurarmos de que você recebeu a notificação. Caso contrário, voltaremos a tentar.