Saltar al contenido principal

Cómo configurar webhooks en POK

Un webhook es una URL que le das a POK para que llame a tus propios sistemas apenas pasa algo con una credencial, en lugar de que tengas que preguntarle a la API una y otra vez. Eliges a cuáles de los cuatro eventos suscribirte, y POK envía una solicitud firmada a esa URL cada vez que ocurre uno de ellos, ya sea que emitas credenciales desde el certifier o a través de la API.

Abre la sección de Webhooks​

Necesitas rol de administrador. "Webhooks" solo aparece en el menú para ese rol: los operadores y los lectores no lo ven.

  1. En la barra de navegación superior, haz clic en el nombre de tu organización.
  2. En el menú que se abre, haz clic en "Webhooks".

Debajo de "Listado de webhooks" vas a encontrar una tarjeta por evento.

Los cuatro eventos a los que puedes suscribirte​

POK ofrece cuatro eventos, cada uno con su propia tarjeta:

  • "Credenciales aceptadas" ("Recibir una notificación cuando se acepte una credencial"): se dispara cuando el receptor acepta la credencial.
  • "Credenciales emitidas" ("Recibir una notificación cuando se emita una credencial"): se dispara cuando la credencial queda completamente emitida, es decir, ya fue aceptada, se envió por correo al receptor y, si es una credencial blockchain NFT, ya se acuñó.
  • "Firma electrónica" ("Recibir una notificación cuando una credencial requiere firma electrónica"): se dispara cuando una credencial necesita un firmante externo, una vez que las firmas propias de POK ya están completas. Esta tarjeta solo aparece si la firma electrónica está habilitada para tu organización; si la esperas y no la ves, habla con tu ejecutivo de cuenta.
  • "Ruta de aprendizaje completada" ("Recibir una notificación cuando un alumno completa una ruta de aprendizaje"): se dispara cuando un destinatario cumple todos los pasos obligatorios de una Ruta de Aprendizaje, más el mínimo de pasos opcionales que pide cada módulo. Se dispara igual sin importar si se espera algo de tus sistemas después: eso depende de cómo configuraste esa Ruta de Aprendizaje en particular, no del evento. Consulta Rutas de Aprendizaje para saber cuándo una Ruta de Aprendizaje espera que actúes.

Cada evento nombra su tipo; los eventos de credenciales también llevan el id de la credencial afectada, y el evento de Ruta de Aprendizaje nombra en cambio la ruta y el destinatario. Webhooks tiene la forma exacta de cada payload. Para consultar el resto de los datos de una credencial a partir del id que trae, llama a la API, que necesita una API key: consulta API keys.

Crea un webhook​

Todas las tarjetas funcionan igual:

  1. Busca la tarjeta del evento que quieres, debajo de "Listado de webhooks".
  2. Escribe la URL en su campo "Url del Webhook".
  3. Haz clic en "+ Crear Webhook".

"+ Crear Webhook" solo se habilita cuando la URL tiene aspecto de dirección real: necesita el esquema "http://" o "https://" y un dominio real, por ejemplo https://www.ejemplo.edu/hooks/pok. Un host suelto o una URL sin esquema no lo habilitan.

Puedes agregar más de una URL al mismo evento. Repite los pasos y aparece una fila nueva en la tabla de esa tarjeta, junto a las que ya tienes; POK envía cada ocurrencia de ese evento a todas las URL de la lista, no solo a la más nueva.

Si la creación falla, la URL queda en el campo para que la corrijas y lo intentes de nuevo sin volver a escribirla.

Apenas una tarjeta tiene al menos una URL, le crece una tabla con las columnas "Fecha de creación", "Url del Webhook" y "Acciones", una fila por URL. Los tres íconos debajo de "Acciones" (una llave, una marca de verificación y una papelera) se explican a continuación.

La clave de firma y el secreto compartido​

Haz clic en el ícono de llave en "Acciones" de una fila para abrir "Claves del webhook". Ahí se muestran dos secretos, solo para esa URL: la "Clave de firma" y el "Secreto compartido". Cada URL que agregas recibe su propio par, incluso si dos URL están suscritas al mismo evento.

Las dos quedan ocultas como una contraseña. Haz clic en el ícono de ojo junto a una para revelarla, o en el ícono de copiar para copiarla directo al portapapeles; POK confirma con "Secreto copiado al portapapeles".

Existen para que tu sistema pueda confirmar que una solicitud realmente vino de POK, no de alguien más, y que no se alteró en el camino:

  • La clave de firma es la que usas para verificar el encabezado "X-Pok-Signature" de la solicitud contra su cuerpo.
  • El secreto compartido es el que vuelve a ti, codificado en base64, en el propio encabezado "Authorization" de la solicitud.

Webhooks tiene los pasos exactos para las dos, incluido un fragmento de TypeScript listo para usar en la verificación de la firma. Como las claves son por URL, usa las de la misma fila que estás verificando: una firma verificada contra la clave de firma de otro webhook nunca va a coincidir, aunque la solicitud sea genuina.

Envía una prueba​

Haz clic en el ícono de marca de verificación de una fila para enviarle a esa URL una solicitud real y completa para su evento, con valores de relleno en lugar de una credencial o un destinatario real. Lleva los mismos encabezados y la misma firma que llevaría un evento genuino, así que es una forma segura de probar un endpoint antes de conectarlo al tráfico real.

POK muestra "Se ha enviado la prueba correctamente." apenas despacha la solicitud. Eso confirma que POK la encoló y la envió; no confirma que tu endpoint la recibió o la aceptó, porque la entrega ocurre después y POK no le informa esa parte al certifier. Para ver si la prueba realmente llega, mira directamente tu propio endpoint (sus logs, o una herramienta de inspección de solicitudes mientras todavía estás configurando todo).

Elimina un webhook​

Haz clic en el ícono de papelera de una fila para eliminar esa URL. No hay paso de confirmación: desaparece apenas haces clic, y esto no se puede deshacer.

Si más adelante necesitas la misma URL otra vez, créala de nuevo. El webhook nuevo recibe una clave de firma y un secreto compartido nuevos; no recupera los anteriores.

No llega nada a tu URL​

Revisa esto en orden:

  1. El evento todavía no pasó. Cada uno se dispara solo con su propia condición, descrita arriba en los cuatro eventos. "Credenciales emitidas", por ejemplo, necesita que la credencial ya esté aceptada y enviada por correo, y también acuñada si es una credencial blockchain NFT: crear o enviar una credencial no alcanza por sí solo para dispararlo.
  2. El evento directamente no está en la página. "Firma electrónica" solo aparece cuando esa función está habilitada para tu organización. Si la esperas y no la ves, habla con tu ejecutivo de cuenta.
  3. POK llegó a tu URL, pero nada te dice qué pasó después. POK llama a tu URL una sola vez por evento y no reintenta. Si tu endpoint está caído, tarda demasiado o rechaza la solicitud, nada en el certifier lo muestra, ni siquiera una prueba: ver "Se ha enviado la prueba correctamente." solo significa que POK despachó la solicitud, no que tu endpoint respondió. Revisa directamente si tu endpoint es alcanzable y mira sus logs; enviar una prueba mientras los observas es la forma más rápida de saberlo.

Llega una llamada pero no puedes verificar que vino de POK​

  1. La verificación de la firma no corre sobre el cuerpo crudo. El HMAC tiene que usar el cuerpo de la solicitud tal cual llegó, antes de que tu código lo parsee. Volver a serializar el JSON, aunque no cambies ni un valor, produce una cadena distinta y una firma distinta. Webhooks tiene la receta exacta y un ejemplo de código que funciona.
  2. Las claves son de otro webhook. Cada URL tiene su propia clave de firma y su propio secreto compartido. Si tu organización tiene más de uno, verificar con las claves de la fila equivocada hace que una solicitud genuina parezca inválida.