Webhooks > Seguridad y manejo


Cualquier persona que conozca la URL de su webhook puede enviarle solicitudes. Active la firma para que su sistema pueda verificar que un webhook realmente proviene de Hyfin y que no fue modificado en el camino. La firma sigue la especificación Standard Webhooks, por lo que sus bibliotecas de verificación funcionan tal cual.


Encabezados en cada webhook

  • webhook-id El id de este mensaje. Es el mismo en cada reintento, así que úselo para detectar un webhook que ya procesó.
  • webhook-timestamp Cuándo se envió este intento, en segundos desde 1970 (hora Unix).
  • webhook-signature Se envía solo cuando la firma está activada. Contiene v1, y después la firma. Mientras un secreto anterior sigue activo tras un cambio, hay dos firmas, separadas por un espacio.

Activar la firma

Cree un secreto de firma para el sitio:

POST
{base_url}/api/v3.1/site/{site_id}/webhook/signingSecret/rotate

Con un cuerpo vacío, Hyfin crea un secreto y lo devuelve una sola vez, como data.secret. Guárdelo en un lugar seguro. No se puede volver a consultar después. Puede enviar el suyo en su lugar, como secret: whsec_ seguido de 24 a 64 bytes aleatorios en base64. Un secreto que usted envía no se devuelve.

Cambiar el secreto

Llame de nuevo al mismo endpoint para reemplazar el secreto. El secreto anterior sigue firmando junto con el nuevo durante 24 horas, para que pueda migrar su sistema sin rechazar webhooks. Establezca previous_secret_expires_in_hours para cambiar ese plazo, de 0 (dejar de usar el secreto anterior de inmediato) a 168 horas.

Consultar o desactivar la firma

GET
{base_url}/api/v3.1/site/{site_id}/webhook/security

Muestra si la firma y el encabezado personalizado están activados. Nunca devuelve un secreto.

POST
{base_url}/api/v3.1/site/{site_id}/webhook/signingSecret/remove

Detiene la firma y elimina todos los secretos del sitio.


Verificar un webhook

La forma más sencilla es usar una biblioteca de Standard Webhooks. Existen para JavaScript, Python, Go, Java, Ruby, PHP y .NET. Pase el cuerpo sin procesar exactamente como llegó, antes de analizar cualquier JSON.

Con la biblioteca standardwebhooks
			
import { Webhook } from 'standardwebhooks'

// Throws when the signature or timestamp is wrong.
const payload = new Webhook(process.env.WEBHOOK_SECRET).verify(rawBody, request.headers)


		

Para verificarlo usted mismo:

  1. Rechace el webhook si webhook-timestamp está a más de unos minutos de la hora actual. Esto evita que se le vuelva a enviar un webhook antiguo.
  2. Una webhook-id, webhook-timestamp y el cuerpo sin procesar con un punto entre cada uno.
  3. Quite whsec_ del inicio de su secreto y decodifique el resto desde base64. Esa es la clave.
  4. Firme el texto unido con HMAC-SHA256 usando esa clave y codifique el resultado en base64.
  5. Acepte el webhook si coincide con alguna entrada v1, en webhook-signature. Compare en tiempo constante.
Sin una biblioteca (Node.js)
			
import crypto from 'node:crypto'

export function verifyWebhook(secret, headers, rawBody) {
	const id = headers['webhook-id']
	const timestamp = Number(headers['webhook-timestamp'])
	if (!id || !Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 5 * 60) return false

	const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
	const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest()

	return (headers['webhook-signature'] ?? '').split(' ').some(entry => {
		const [version, signature = ''] = entry.split(',')
		const received = Buffer.from(signature, 'base64')
		return version === 'v1' && received.length === expected.length && crypto.timingSafeEqual(received, expected)
	})
}


		

Encabezado personalizado

Si su sistema solo puede verificar un encabezado fijo, por ejemplo en una puerta de enlace de API, Hyfin puede enviar un encabezado de su elección en cada webhook. Esto funciona con o sin firma, pero la firma es más segura porque el valor nunca cambia.

POST
{base_url}/api/v3.1/site/{site_id}/webhook/authHeader/set

Envíe name y value. El valor debe tener de 16 a 2,048 caracteres ASCII visibles y puede contener espacios en medio. El nombre no puede comenzar con webhook- ni ser un encabezado que ya incluye toda solicitud, como Content-Type o Host.

POST
{base_url}/api/v3.1/site/{site_id}/webhook/authHeader/remove

Deja de enviar el encabezado.


Manejo de webhooks

  • Responda rápido. Responda con cualquier estado 2xx en cuanto el webhook esté almacenado de forma segura y haga el trabajo lento después. Un webhook sin respuesta 2xx en 30 segundos se considera fallido y se vuelve a enviar.
  • Espere repeticiones. El mismo webhook puede llegar más de una vez. Omita cualquier webhook-id que ya haya procesado.
  • Espere que lleguen desordenados. Un webhook reintentado puede llegar después de uno más reciente del mismo registro. Cuando el orden importe, vuelva a leer el registro con su endpoint Get.
  • Verifique la firma antes de actuar sobre un webhook.

Consulte Webhooks > Introducción para saber cuándo ocurren los reintentos.