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:
plain 34.226.254.178, 44.198.3.59, 34.223.185.46, 100.20.205.117

Prod/Sandbox:
plain 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: