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.
Cree un secreto de firma para el sitio:
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.
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.
Muestra si la firma y el encabezado personalizado están activados. Nunca devuelve un secreto.
Detiene la firma y elimina todos los secretos del sitio.
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.
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:
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)
})
}
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.
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.
Deja de enviar el encabezado.
Consulte Webhooks > Introducción para saber cuándo ocurren los reintentos.