Fluxo de Atualização do Webhook para Tokens Dinâmicos

Quando há a necessidade de consulta em um endpoint para coletar um token de autenticação que vá junto com o webhook no momento do disparo, é preciso montar uma integração customizada para atender à essa demanda.

📘

Este fluxo utiliza webhook

Para implementar integrações a partir de webhooks é necessário uma configuração prévia através da própria API Gupy: Acesse aqui para mais informações de configuração de webhooks

❗️

Atenção!

Não é possível fechar VPN como rota para entrega do Webhook.

A URL usada para receber o Webhook (postbackUrl) DEVE ser um endereço HTTPS válido, exposto publicamente.

URLs com alta taxa de erro (100% dos erros nos últimos 7 dias) serão removidas sem aviso prévio.

O Webhook espera uma resposta em 30.000 ms. Caso a resposta não tenha ocorrido antes deste tempo, consideramos um timeout, consequentemente, um erro.

A Gupy garante pelo menos uma entrega, então podem haver várias notificações do mesmo evento, use a propriedade id para identificar duplicatas.

Não há garantia de ordem de entrega, use a propriedade date para verificar qual evento aconteceu primeiro e classifique os eventos.

NÃO USE serviços como requestcatcher, eles podem expor dados.

Quando setamos algum valor no clientHeaders, o header padrão 'Content-type: application/json;charset=utf-8' não é mais enviado, pois o valor dos headers passa a ser o que foi definido. Se for necessário que o Content-type tenha sempre o valor padrão, recomendamos passá-lo junto no clientHeaders.

Habilitando Endpoints

Para utilizar este fluxo, é necessário utilizar o Bearer Token gerado nas configurações avançadas da plataforma. Acesse nossa seção de autenticação para saber como gerar o token de autenticação.

Abaixo encontra-se uma sugestão dos endpoints que devem ser habilitados obrigatoriamente para o funcionamento perfeito deste fluxo.

Fluxo de Integração:

1. Cadastrar o webhook noPOST Webhook utilizando a função clientHeaders, onde pode atribuir um campo e valor que acompanha o Webhook, como por exemplo campo "token" e value "abc123". Esse processo só precisa ser feito uma vez. É necessário guardar o postbackUrl, id e action do response para uso futuro.

Exemplo de requisição de criação de um webhook:

curl --request POST \
     --url https://api.gupy.io/api/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "action": "application.completed",
  "status": "active",
  "techOwnerEmail": "[email protected]",
  "techOwnerName": "Nome Sobrenome",
  "postbackUrl": "https://urlDoIntegrador.net",
  "clientHeaders": {
    "apiKey": "apiToken",
    "content-type": "application/json",
    "token": "abc123"
  },
}

Exemplo de resposta dado pelo endpoint de configuração de webhook

{
  "id": "d5b2eca6-09c5-4014-9eb8-1d729dd2e3d6",
  "action": "application.completed",
  "postbackUrl": "https://370c0c61b68af08c6f622202011f1e1d.m.pipedream.net",
  "status": "active"
}

O campo "id" retornado quando ocorre a ativação com sucesso de um webhook é a chave da instância, que deverá ser utilizado posteriormente como mesma chave para alterar qualquer configuração deste webhook ou mesmo inativá-lo.

2. De tempos em tempos, de acordo com a duração do token, realizar o seguinte processo através do: Updating Webhook

• Informar id guardado no campo webhookId;
• Informar valor do campo action;
• Informar valor do campo postbackUrl;
• No array de clientHeaders, enviar o novo valor do campo "token".

Exemplo de requisição de atualização do webhook com novo token

curl --request PUT \
     --url https://api.gupy.io/api/v1/webhooks/d5b2eca6-09c5-4014-9eb8-1d729dd2e3d6 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "action": "application.completed",
  "clientHeaders": {
    "apiKey": "apiToken",
    "content-type": "application/json",
    "token": "zxy321"
  },
  "status": "active",
  "techOwnerName": "Nome Sobrenome",
  "techOwnerEmail": "[email protected]",
  "postbackUrl": "https://urlDoIntegrador.net"
}
'