Configurar webhooks
Vamos mostrar-lhe como usar os nossos webhooks para receber notificações em tempo real.
Na Pomelo, a gente usa webhooks para informar você sobre os principais eventos que afectam a sua operação:
- Quando uma transação de pagamento é iniciada (CARDS)
- Se um ajuste for feito em uma transação existente (CARDS)
- Quando o estado de uma transação é resolvido (CARDS)
- Cada vez que o estado de uma remessa é modificado (CARDS)
- Quando uma atividade é criada ou atualizada (BANKING)
- Quando a identidade de um usuário é validada (IDENTITY)
Sempre que esses eventos ocorrem, fazemos uma solicitação POST para um endpoint HTTPS no seu servidor, usando um objeto JSON com as informações.
Como configurar um webhook
Etapa 1: Criar seu endpoint
Você deve criar no seu servidor um endpoint que atenda a estes requisitos:
- Receber tráfego por HTTPS
- Receber um objeto JSON no corpo da solicitação
Etapa 2: Reconhecer nossos IPs
A gente sempre se comunica desde IPs próprios e específicos. Recomendamos que você aceite apenas as solicitações de um dos nossos IPs e rejeite qualquer outro.
Stage:
34.226.254.178
44.198.3.59
34.223.185.46
100.20.205.117
Prod/Sandbox:
34.206.159.176
52.0.20.124
35.84.78.117
52.43.46.111
Etapa 3: Validar nossa assinatura
Como medida de segurança, assinamos todas as solicitações que enviamos usando hmac-sha256, assim você pode ter a certeza de que são nossas. Durante o processo de onboarding, a gente vai compartilhar com você uma api-key e uma api-secret, conforme é descrito na Troca de chaves.
Em cada solicitação, enviamos headers HTTP que irão permitir que você verifique se a assinatura está correta:
x-api-key: permitirá que você identifique qual api-secret usar (no caso que vários pares de api-key e api-secret tenham sido configurados).
x-signature: inclui a assinatura digital (body + timestamp + endpoint) que você terá de validar para garantir a integridade da solicitação. Nós geramos essa assinatura usando o api-secret que compartilhamos com você anteriormente. Se ela não corresponder, você terá de rejeitar a solicitação.
x-timestamp : inclui o horário em que a solicitação foi assinada no formato unix-epoch para que você gere novamente a assinatura e confirme se ela é válida. No caso de Autorizar transacção, você também vai conseguir verificar se a assinatura ainda não expirou (elas expiram após 1 minuto).
x-endpoint: é o endpoint que utilizamos para gerar a assinatura e para o qual a solicitação foi criada. É necessário utilizar este header para gerar novamente a assinatura a ser validada, compará-lo com o endpoint do seu serviço e verificar se eles correspondem.
Abaixo está 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 solicitaremos que você assine a resposta.
Os headers HTTP que você deve enviar são:
x-api-key: esse header permitirá identificar qual api-secret você deve usar no caso de múltiplos pares de api-key e api-secret estarem configurados.
x-signature: esse header contém a assinatura digital (body + timestamp + endpoint) que você deverá verificar para garantir a integridade do request. Se a assinatura não coincidir, você deverá rejeitar o pedido.
x-timestamp: esse header contém o momento em que o pedido foi assinado no formato unix-epoch, para que você possa verificar se a assinatura expirou.
x-endpoint: o endpoint ao qual o pedido foi feito e que foi usado para gerar a assinatura. Use esse header para regenerar a assinatura a ser validada, compará-lo com o endpoint do seu serviço e verificar se coincidem.
Exemplos de implementação de validação e assinatura de pedidos
Em nosso repositório, você encontrará exemplos de implementação do algoritmo de geração e validação de assinatura em várias linguagens. Ver repositório
Passo 4: Resposta para casos que não precisam de assinatura
Esperamos uma resposta do tipo 2XX para garantir que você recebeu a notificação. Caso contrário, tentaremos novamente.