Como configurar webhooks na POK
Um webhook é uma URL que você dá à POK para que ela chame os seus próprios sistemas assim que algo acontece com uma credencial, em vez de você ficar perguntando à API repetidas vezes. Você escolhe a quais dos quatro eventos se inscrever, e a POK envia uma requisição assinada para essa URL toda vez que um deles acontece, seja emitindo credenciais pelo certifier ou pela API.
Abra a seção Webhooks
Você precisa de perfil de administrador. "Webhooks" só aparece no menu para esse perfil: operadores e leitores não o veem.
- Na barra de navegação superior, clique no nome da sua organização.
- No menu que se abre, clique em "Webhooks".
Embaixo de "Lista de Webhooks" você vai encontrar um cartão por evento.
Os quatro eventos aos quais você pode se inscrever
A POK oferece quatro eventos, cada um com seu próprio cartão:
- "Credenciais Aceitas" ("Receba uma notificação quando uma credencial for aceita"): dispara quando o titular aceita a credencial.
- "Credenciais Emitidas" ("Receba uma notificação quando uma credencial for emitida"): dispara quando a credencial fica totalmente emitida, ou seja, já foi aceita, enviada por e-mail ao titular e, se for uma credencial blockchain NFT, já foi cunhada.
- "Assinatura eletrônica" ("Receber uma notificação quando uma credencial requer assinatura eletrônica"): dispara quando uma credencial precisa de um signatário externo, depois que as assinaturas da própria POK já estão completas. Esse cartão só aparece se a assinatura eletrônica estiver habilitada para a sua organização; se você espera por ele e não o vê, fale com o seu executivo de contas.
- "Trilha concluída" ("Receber uma notificação quando um aluno conclui uma trilha de aprendizagem"): dispara quando um destinatário cumpre todas as etapas obrigatórias de uma Rota de Aprendizagem, mais o mínimo de etapas opcionais que cada grupo pede. Ele dispara do mesmo jeito, independentemente de haver algo esperado dos seus sistemas depois: isso depende de como você configurou aquela Rota de Aprendizagem, não do evento. Consulte Rotas de Aprendizagem para saber quando uma Rota de Aprendizagem espera uma ação sua.
Cada evento nomeia o seu tipo; os eventos de credenciais também trazem o id da credencial afetada, e o evento de Rota de Aprendizagem nomeia a rota e o destinatário no lugar disso. Webhooks tem o formato exato de cada payload. Para buscar o restante dos dados de uma credencial a partir do id que ela traz, chame a API, que exige uma chave de API: veja Chaves de API.
Crie um webhook
Todos os cartões funcionam da mesma forma:
- Encontre o cartão do evento que você quer, embaixo de "Lista de Webhooks".
- Digite a URL no campo "URL do Webhook" dele.
- Clique em "+ Criar Webhook".
"+ Criar Webhook" só é habilitado quando a URL parece um endereço real: precisa do esquema "http://" ou "https://" e de um domínio real, por exemplo https://www.exemplo.edu/hooks/pok. Um host solto ou uma URL sem esquema não o habilitam.
Você pode adicionar mais de uma URL ao mesmo evento. Repita os passos e uma nova linha aparece na tabela daquele cartão, ao lado das que você já tem; a POK envia cada ocorrência daquele evento para todas as URLs da lista, não só para a mais nova.
Se a criação falhar, a URL permanece no campo para você corrigi-la e tentar de novo sem precisar digitá-la outra vez.
Assim que um cartão tem pelo menos uma URL, cresce nele uma tabela com as colunas "Data de Criação", "URL do Webhook" e "Ações", uma linha por URL. Os três ícones embaixo de "Ações" (uma chave, uma marca de verificação e uma lixeira) são explicados a seguir.
A chave de assinatura e o segredo compartilhado
Clique no ícone de chave em "Ações" de uma linha para abrir "Chaves do Webhook". Ali aparecem dois segredos, só dessa URL: a "Chave de Assinatura" e o "Segredo Compartilhado". Cada URL que você adiciona recebe o seu próprio par, mesmo que duas URLs estejam inscritas no mesmo evento.
As duas ficam ocultas como uma senha. Clique no ícone de olho ao lado de uma para revelá-la, ou no ícone de copiar para copiá-la direto para a área de transferência; a POK confirma com "Segredo copiado para a área de transferência".
Elas existem para que o seu sistema consiga confirmar que uma requisição realmente veio da POK, e não de outra pessoa, e que não foi alterada no caminho:
- A chave de assinatura é a que você usa para verificar o cabeçalho "X-Pok-Signature" da requisição contra o seu corpo.
- O segredo compartilhado é o que volta para você, codificado em base64, no próprio cabeçalho "Authorization" da requisição.
Webhooks tem os passos exatos para as duas, incluindo um trecho de TypeScript pronto para usar na verificação da assinatura. Como as chaves são por URL, use as da mesma linha que você está verificando: uma assinatura verificada contra a chave de assinatura de outro webhook nunca vai coincidir, mesmo que a requisição seja genuína.
Envie um teste
Clique no ícone de marca de verificação de uma linha para enviar a essa URL uma requisição real e completa do seu evento, com valores de preenchimento no lugar de uma credencial ou de um destinatário de verdade. Ela carrega os mesmos cabeçalhos e a mesma assinatura que um evento genuíno carregaria, então é uma forma segura de testar um endpoint antes de ligá-lo ao tráfego real.
A POK mostra "Teste enviado com sucesso." assim que despacha a requisição. Isso confirma que a POK a enfileirou e enviou; não confirma que o seu endpoint a recebeu ou aceitou, porque a entrega acontece depois e a POK não informa essa parte de volta ao certifier. Para ver se o teste realmente chega, observe diretamente o seu próprio endpoint (os logs dele, ou uma ferramenta de inspeção de requisições enquanto você ainda está configurando tudo).
Exclua um webhook
Clique no ícone de lixeira de uma linha para excluir essa URL. Não existe etapa de confirmação: ela desaparece assim que você clica, e isso não pode ser desfeito.
Se você precisar da mesma URL de novo mais adiante, crie-a de novo. O novo webhook recebe uma chave de assinatura e um segredo compartilhado novos; ele não recupera os antigos.
Nada está chegando na sua URL
Verifique isto em ordem:
- O evento ainda não aconteceu de fato. Cada um dispara só com a sua própria condição, descrita acima em os quatro eventos. "Credenciais Emitidas", por exemplo, precisa que a credencial já esteja aceita e enviada por e-mail, e também cunhada se for uma credencial blockchain NFT: criar ou enviar uma credencial não basta sozinho para disparar o evento.
- O evento simplesmente não está na página. "Assinatura eletrônica" só aparece quando esse recurso está habilitado para a sua organização. Se você espera vê-lo e não vê, fale com o seu executivo de contas.
- A POK chegou até a sua URL, mas nada diz o que aconteceu depois. A POK chama a sua URL uma única vez por evento e não tenta de novo. Se o seu endpoint está fora do ar, demora demais ou rejeita a requisição, nada no certifier mostra isso, nem mesmo um teste: ver "Teste enviado com sucesso." só significa que a POK despachou a requisição, não que o seu endpoint respondeu. Verifique diretamente se o seu endpoint está acessível e olhe os logs dele; enviar um teste enquanto você os observa é a forma mais rápida de saber.
Uma chamada chega, mas você não consegue verificar que veio da POK
- A verificação da assinatura não está rodando sobre o corpo bruto. O HMAC precisa usar o corpo da requisição exatamente como ele chegou, antes de o seu código analisá-lo. Serializar o JSON de novo, mesmo sem mudar um único valor, produz uma string diferente e uma assinatura diferente. Webhooks tem a receita exata e um exemplo de código funcionando.
- As chaves são de outro webhook. Cada URL tem a sua própria chave de assinatura e o seu próprio segredo compartilhado. Se a sua organização tem mais de um, verificar com as chaves da linha errada faz uma requisição genuína parecer inválida.