Skip to main content
A plataforma envia notificações de acompanhamento do status de movimentações, como recebimento do pedido, andamento da movimentação, conclusão (se de inclusão, já contendo a numeração de carteirinha e a data de início de vigência; se de exclusão, já contendo a data fim da vigência do benefício) e recusa do pedido. Essas notificações são hoje enviadas via e-mail para os representantes de RH cadastrados na empresa. Com a API essa funcionalidade foi expandida para que essas notificações também possam ser enviadas para uma URL da empresa, que você mesmo cadastra na Plataforma do RH. A Pipo faz uma requisição HTTP em modo POST com os dados da notificação no corpo da requisição, codificados em JSON.

​
Cadastro do webhook

O webhook é cadastrado na Plataforma do RH, na mesma tela em que você gerencia as credenciais da API.
1

Abra a tela da API

Na Plataforma do RH, acesse o menu API.
2

Cadastre o webhook

Na seção Webhook, clique em Cadastrar webhook e informe a URL e a chave de autorização.
3

Aguarde a configuração valer

A Pipo grava a configuração em segundo plano, e ela pode levar alguns minutos para valer. Nesse intervalo a tela já mostra a URL enviada, com o aviso de que a configuração está sendo aplicada.
  • URL: Endereço para o qual a Pipo fará uma requisição HTTP em modo POST com os dados da notificação no corpo da requisição, codificados em JSON. A URL precisa começar com https:// e ser acessível pela internet.
  • Chave de autorização: Texto combinado entre você e o seu servidor, que a Pipo envia no header Authorization da requisição, em modo Basic (codificado em base64, segundo a especificação HTTP — RFC 7617). Veja abaixo como ela funciona.
Para trocar a URL ou a chave, use Alterar webhook. A chave nunca é exibida de novo, então ao alterar você informa a chave outra vez, mesmo que só a URL mude. A tela cadastra e altera o webhook, mas não tem opção de remover: para deixar de receber as notificações, fale com o seu Gerente de Contas da Pipo.
Homologação e produção são independentes. O webhook cadastrado na Plataforma do RH de homologação (toro.pipo.health) não vale em produção (app.piposaude.com.br), e vice-versa. Cadastre nos dois ambientes que for usar.

​
Como a chave de autorização funciona

A Pipo converte a chave para base64 e a envia em todas as notificações, no header Authorization:
O formato recomendado é usuario:senha, o padrão do HTTP Basic. O seu servidor decodifica o base64 e separa o usuário e a senha no primeiro :. Para conferir o valor que o seu servidor recebe, decodifique o base64:
  • A Pipo aceita qualquer texto não vazio como chave e não valida o formato. O que importa é o que o seu servidor espera. Servidores com autenticação Basic padrão esperam usuario:senha e tendem a recusar a requisição (401) quando a chave não tem :. Se o seu servidor compara o valor inteiro, como um token, qualquer texto funciona, desde que seja o mesmo nos dois lados.
  • Use um segredo exclusivo para o webhook e não reutilize a senha de outro sistema: o base64 é apenas uma codificação, não uma criptografia.
  • A URL do webhook precisa ser https porque a chave viaja no header.

​
Notificações enviadas

Todas as notificações são enviadas com Método POST e Autorização HTTP Basic, com a chave de autorização cadastrada.
Enviada quando o pedido de inclusão é recebido. Identificada por enrollment-type: inclusion e status: enrollment-created.
Enviada quando o pedido de exclusão é recebido. Identificada por enrollment-type: exclusion e status: enrollment-created.
Enviada quando a movimentação muda de etapa, depois de solicitada e antes de concluída. Identificada por status igual a waiting-for-broker, waiting-for-carrier, manual-fallback ou waiting-for-beneficiary. Ver Webhook Status.Pode ser enviada mais de uma vez para a mesma movimentação, e o mesmo status pode se repetir. Quando há um motivo, como um documento pendente, ele vem em status-details. Os demais campos são os mesmos da notificação de solicitada, e os beneficiários family e dependent seguem o formato dela.
Enviada quando a inclusão é concluída, já contendo a numeração de carteirinha (id-card-number) e a data de início de vigência (start-date). Identificada por enrollment-type: inclusion e status: enrollment-completed.
Enviada quando a exclusão é concluída, já contendo a data fim da vigência do benefício (end-date). Identificada por enrollment-type: exclusion e status: enrollment-completed.
Enviada quando um pedido é recusado e a movimentação não chega a ser criada. Identificada por status: enrollment-creation-failed. Traz os dados da empresa e, em benefits, o produto e o motivo da recusa (reason). Cada pedido recusado é notificado uma vez.Hoje o único motivo enviado é enrollment-already-exists: já existe uma movimentação ativa do mesmo tipo para o beneficiário.

​
Campos do payload

​
Entrega das notificações

  • Responda com 2xx em até 5 segundos. Uma resposta com outro status, uma resposta que demora mais ou uma falha de conexão é registrada pela Pipo como notificação não entregue.
  • Não há reenvio automático. A notificação que falha não é enviada de novo. Se o seu servidor ficou fora do ar, consulte as movimentações em andamento ou o status da requisição pela API.
  • Trate repetições. A mesma notificação pode chegar mais de uma vez, e o mesmo status de andamento pode se repetir. Use o enrollment-id e o status (e o request-id, quando houver) para ignorar o que já foi processado.