WebhookAuthentication

¿Para que sirve esto? Cuando HighLevel le avisa a su sistema que algo paso (por ejemplo, "se creo un contacto nuevo" cuando un prospecto llena el formulario de admisiones), esa notificación viaja firmada digitalmente. Esta guia le explica a su desarrollador como verificar que esa notificación realmente viene de HighLevel y no de alguien más — un paso de seguridad que no conviene saltarse.

Guia de autenticación de webhooks

Como funciona

1. Recepcion del webhook

Cuando tu endpoint recibe una peticion de webhook, incluira lo siguiente:

• Headers:
• x-wh-signature: la firma digital del payload.
• Body: el payload que contiene el timestamp, el webhook Id y los datos.

Ejemplo de payload:

{
  "timestamp": "2025-01-28T14:35:00Z",
  "webhookId": "abc123xyz",
  ...<add_other_webhook_data>
}

2. Verificación de la firma

Para verificar la autenticidad de la peticion de webhook:

1. Obten el header x-wh-signature de la peticion.
2. Usa la llave publica mencionada abajo para verificar la firma.
3. Calcula la firma de tu lado usando el payload y la llave publica.
4. Compara tu firma calculada con el header x-wh-signature.

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAokvo/r9tVgcfZ5DysOSC
Frm602qYV0MaAiNnX9O8KxMbiyRKWeL9JpCpVpt4XHIcBOK4u3cLSqJGOLaPuXw6
dO0t6Q/ZVdAV5Phz+ZtzPL16iCGeK9po6D6JHBpbi989mmzMryUnQJezlYJ3DVfB
csedpinheNnyYeFXolrJvcsjDtfAeRx5ByHQmTnSdFUzuAnC9/GepgLT9SM4nCpv
uxmZMxrJt5Rw+VUaQ9B8JSvbMPpez4peKaJPZHBbU3OdeCVx5klVXXZQGNHOs8gF
3kvoV5rTnXV0IknLBXlcKKAQLZcY/Q9rG6Ifi9c+5vqlvHPCUJFT5XUGG5RKgOKU
J062fRtN+rLYZUV+BjafxQauvC8wSWeYja63VSUruvmNj8xkx2zE/Juc+yjLjTXp
IocmaiFeAO6fUtNjDeFVkhf5LNb59vECyrHD2SQIrhgXpO4Q3dVNA5rw576PwTzN
h/AMfHKIjE4xQA1SZuYJmNnmVZLIZBlQAF9Ntd03rfadZ+yDiOXCCs9FkHibELhC
HULgCsnuDJHcrGNd5/Ddm5hxGQ0ASitgHeMZ0kcIOwKDOzOU53lDza6/Y09T7sYJ
PQe7z0cvj7aE4B+Ax1ZoZGPzpJlZtGXCsu9aTEGEnKzmsFqwcSsnw3JB31IGKAyk
T1hhTiaCeIY/OwwwNUY2yvcCAwEAAQ==
-----END PUBLIC KEY-----

Si coinciden, el payload es valido y proviene de una fuente confiable.

3. Proteccion contra ataques de repeticion (replay)

Para protegerte contra ataques de repeticion:

• Asegurate de que el timestamp del payload este dentro de una ventana de tiempo aceptable (por ejemplo, 5 minutos).
• Rechaza cualquier peticion con valores de webhookId duplicados.

4. Rotacion de la llave publica

Mantente al tanto de tu correo y de nuestros canales sociales para avisos sobre la rotacion de la llave publica. La llave publica en este documento es la que debes usar para validar el payload del webhook.

Código de ejemplo

Ejemplo de como verificar la firma en Node.js:

const crypto = require('crypto');

const publicKey = `<use_the_above_key>`;

function verifySignature(payload, signature) {
    const verifier = crypto.createVerify('SHA256');
    verifier.update(payload);
    verifier.end();

    return verifier.verify(publicKey, signature, 'base64');
}

// Ejemplo de uso
const payload = JSON.stringify({
  "timestamp": "2025-01-28T14:35:00Z",
  "webhookId": "abc123xyz",
  ...<add_other_webhook_data>
});

const signature = "<received-x-wh-signature>";
const isValid = verifySignature(payload, signature);

return isValid;

Resumen

Estas funciones nuevas mejoran significativamente la seguridad de las integraciones por webhook. Al incluir un timestamp, un webhook Id y un payload firmado digitalmente, garantizamos que tus datos se mantengan seguros y confiables. ¡Implementa estos cambios hoy para mantener tus integraciones robustas y seguras!