Cómo enviar un secreto de firma de webhook a un cliente de forma segura

El secreto de firma de un webhook es una credencial, no un detalle de configuración. Envíalo como enviarías una contraseña: confirma quién lo recibe, entrégalo por un canal que no guarde copias y asegúrate de que acaba en un almacén de secretos y no en un ticket. En pocas palabras: un enlace secreto de un solo uso enviado a un contacto verificado, con las instrucciones de configuración por separado.

El resto de esta guía trata la elección del canal, las comprobaciones previas al envío, qué debe hacer el cliente con el valor y cómo gestionar la rotación y los problemas sin volver a pegar el secreto nunca.

¿Qué canal debe llevar el secreto?

Elige el canal según dos preguntas: ¿puedes confirmar quién puede abrirlo? ¿Cuántas copias deja? El correo y el chat no superan la segunda, porque cada mensaje se conserva, se sincroniza y se exporta mucho después de terminar la entrega.

Un portal de clientes con inicio de sesión individual es una buena primera opción si existe. Da acceso a una persona concreta, no a un hilo compartido del proyecto, y quítalo cuando termine la entrega.

Un enlace de un solo uso mantiene la credencial fuera del correo o del mensaje de chat que usas para coordinar la entrega. Con LinkPilot, el secreto se cifra en tu navegador antes de guardarse, la copia almacenada se destruye tras abrirse una vez y puedes hacer que el enlace expire al cabo de una hora, un día o una semana. Los planes Pro añaden una frase de contraseña que comunicas por otro canal. Estos controles limitan la entrega, pero no sustituyen la comprobación de que al otro lado está la persona correcta.

La mensajería cifrada es la alternativa cuando ninguna de las anteriores es práctica. El cifrado en tránsito no arregla un mensaje mal dirigido ni un grupo con demasiados miembros, así que la comprobación del destinatario importa todavía más.

Elijas lo que elijas, usa el correo y el chat sin cifrar solo para coordinar. Incluso los servicios que cifran en tránsito dejan la conservación de mensajes, las copias de seguridad y el acceso a las cuentas fuera de tu control.

Verifica al cliente y al destinatario

Un canal seguro no sirve de nada si el secreto llega a la bandeja de entrada equivocada. Antes de enviarlo, confirma que la persona que lo pide es la responsable de la integración y que la vía que vas a usar es realmente suya.

• Confirma la identidad con un registro conocido. Usa una ficha de contacto de confianza, una relación comercial existente o el proceso habitual del cliente. Un solicitante nuevo, un cambio repentino de contacto o una urgencia inusual merecen una comprobación independiente.
• Lee la dirección carácter por carácter, sobre todo si la copias de un ticket o de un mensaje reciente. Los nombres parecidos y las bandejas compartidas son donde se producen los errores.
• Revisa quién más tiene acceso. Antes de compartir a través de un portal o un espacio de trabajo, mira su lista de miembros y quita a quien no necesite la credencial.
• Confirma la entrega por un segundo canal. Si el enlace fue por correo, pregunta por un número de teléfono conocido o por el canal habitual del proyecto si el acceso ha funcionado. No incluyas el secreto en ese mensaje.

Comparte el secreto con la única persona que va a configurar el endpoint y deja que lo guarde en el almacén de secretos del propio cliente. Si varios ingenieros lo necesitan, los controles de acceso de ese almacén son el lugar adecuado para decidir quién lo ve, no copias separadas para cada uno.

Prepara el secreto antes de la entrega

Decide a qué pertenece la credencial, dónde debe guardarla el cliente y cuánto tiempo debe seguir abierta la entrega. Esa preparación hace que la rotación y la resolución de problemas posteriores sean mucho menos confusas.

• Un secreto por cliente o por endpoint. Reutilizarlo significa que una sola exposición alcanza a todas las integraciones que comparten el valor, y que rotarlo para un cliente afecta a todos. Lleva un registro interno de a qué endpoint pertenece cada secreto, sin duplicar el valor en las notas del proyecto.
• Guarda tu propia copia en un gestor de secretos. No en un archivo de texto local, un ticket o un documento compartido. La misma disciplina se aplica a compartir claves de API: limita quién puede llegar a la credencial y haz que la entrega dure poco.
• Fija un plazo para recogerlo. Da al cliente tiempo suficiente para obtener el valor y terminar la configuración, y no más. Un enlace que se destruye tras abrirse una vez y expira en un día cubre la mayoría de las entregas; si el plazo vence, crea uno nuevo en lugar de reabrir el anterior.
• Envía las instrucciones de configuración por separado. La URL del endpoint, la cabecera de la firma y los pasos de verificación van en la documentación del cliente o en el canal del proyecto. Mantenerlos aparte del secreto significa que una página de instrucciones copiada no es también una credencial copiada.

Ayuda al cliente a guardarlo y usarlo de forma segura

La entrega no termina cuando el cliente puede leer el valor. Termina cuando el servidor puede leerlo de forma segura y lo usa para verificar las firmas entrantes.

• Guárdalo en un gestor de secretos o en una variable de entorno protegida que pueda leer el proceso del servidor, con el acceso limitado a la aplicación y a las personas que la operan.
• Mantenlo fuera del código fuente, los registros y las cargas útiles del webhook. El secreto sirve para calcular o verificar una firma. Nunca viaja en el cuerpo de la solicitud y no debe aparecer en la salida de depuración, los repositorios ni los tickets de soporte. Comprueba qué captura tu herramienta de despliegue antes de activar diagnósticos detallados.
• Verifica las firmas en el servidor. El receptor vuelve a calcular la firma sobre el cuerpo sin procesar de la solicitud con el secreto compartido y la compara con la cabecera que fijó el emisor. La firma demuestra que la solicitud es auténtica y no se ha alterado; no cifra la carga útil. La guía de HackerOne sobre cómo firmar webhooks explica por qué importan tanto el cuerpo sin procesar como el secreto correcto.
• Lanza un evento de prueba. Pide al cliente que confirme que se acepta una firma válida y se rechaza una estropeada a propósito. Así se detectan los errores habituales: el secreto de otro endpoint o un cuerpo analizado antes de la verificación. Separa las credenciales de prueba y de producción cuando la integración lo permita.

Reduce el riesgo después de la entrega

La entrega debe dejar un registro útil, no un rastro de copias de más.

• Registra quién estaba autorizado y cuándo. Anota el destinatario, el endpoint o el cliente y la hora de la entrega. Nunca el valor. Si no puedes saber si un enlace se abrió o quién podía acceder a una carpeta compartida, tómalo como motivo para endurecer el proceso la próxima vez.
• Rótalo ante cualquier sospecha de exposición. Un secreto pegado en un ticket, enviado a la dirección equivocada o encontrado en un registro ya no es privado. Genera uno de reemplazo, actualiza el endpoint e invalida el valor antiguo. Eliminar un enlace compartido no deshace una exposición; solo la rotación lo hace.
• Acuerda ahora el proceso de rotación. Decide quién pide, crea e instala el reemplazo, si la implementación admite un breve solapamiento y cómo vas a probar el valor nuevo antes de retirar el antiguo. Un procedimiento conocido es mejor que un intercambio urgente en plena caída del servicio.
• Limpia. Cuando el cliente confirme que lo ha recogido, revoca el acceso temporal y elimina las copias sueltas en borradores, tickets y notas. Revisa las reglas de conservación de cada sistema implicado; eliminar un mensaje de una vista rara vez lo quita de las copias de seguridad.

Resuelve problemas sin exponer el secreto

Un problema de entrega no justifica reenviar la credencial por un canal más débil. Primero averigua cuál de estas tres cosas falla: el cliente no puede recoger el secreto, no puede configurar el endpoint o recibe solicitudes pero no puede validar las firmas.

• La recogida falló o el plazo venció. Vuelve a confirmar el destinatario y prepara una nueva entrega controlada. No pegues el valor en un ticket ni pidas al cliente que te devuelva el suyo para compararlo.
• La firma no coincide. Casi siempre es un problema en los datos de verificación: el secreto equivocado para ese endpoint, un cuerpo que se reformateó antes de calcular el hash o una cabecera mal leída. Pide al cliente que pruebe con un evento conocido mediante las herramientas de prueba del emisor.
• Las solicitudes no llegan nunca. Es un problema de entrega o de enrutamiento, no de credenciales. Revisa las marcas de tiempo, los códigos de respuesta y la selección del endpoint antes de que nadie piense en rotar. La documentación de webhooks de Stripe es un buen modelo para separar el registro del endpoint y la entrega de eventos de la verificación de firmas.
• Comparte diagnósticos con los datos sensibles ocultos. El ID del evento, la marca de tiempo, el endpoint y el tipo de error bastan. Quita el secreto, la firma completa cuando sea sensible y los campos privados de la carga útil, y revisa lo que has ocultado antes de enviar una solicitud de ejemplo.

Verifica al destinatario, entrega el secreto una vez por un canal que lo olvide, asegúrate de que acaba en un almacén de secretos y rótalo sin dudar si puede haberse filtrado. Para ver cómo encajan los enlaces de un solo uso en el trabajo de ingeniería en general, consulta compartir enlaces de forma segura para desarrolladores.