ForHosting KIT · Utilidades de desarrollo

Cómo verificar la firma de un webhook con HMAC

La verificación de firmas webhook suele fallar en los límites: el framework modifica el cuerpo, la cabecera se interpreta con demasiada flexibilidad o una comparación normal filtra información temporal.

● BetaGratis · en su navegador

Ejecutar — gratis Cómo funciona y API

Úselo desde WebAPIEmailTelegramApp pronto

Esta capacidad convierte el algoritmo HMAC y la cabecera del proveedor en una lista ordenada y precisa. No necesita el cuerpo, el secreto ni la firma. Use el resultado para implementar o revisar el endpoint y contraste el formato de fecha, la codificación y la tolerancia de repetición con la documentación del proveedor.

Empiece por los bytes que firmó el proveedor

Conserve exactamente los bytes recibidos antes de interpretar el cuerpo. Analizar y volver a serializar JSON puede cambiar espacios, orden, escapes, Unicode o saltos de línea. Lea la cabecera indicada sin distinguir mayúsculas en su nombre, pero valide estrictamente su valor. El proveedor puede enviar un resumen simple o incluir versión, fecha y varias firmas. Siga su gramática documentada, rechace valores ausentes, vacíos, duplicados o mal formados y mantenga el secreto en un gestor protegido, nunca en registros ni en esta herramienta.

Reconstruya, calcule y compare en el orden correcto

Reconstruya exactamente el mensaje firmado: puede ser el cuerpo sin procesar o una fecha, un separador y el cuerpo. Respete el orden y la codificación documentados. Calcule el HMAC con el secreto y el algoritmo normalizado, y codifique el resultado como exija el proveedor. Decodifique ambas firmas a bytes de igual longitud y use una comparación de tiempo constante. Una codificación inválida o una longitud distinta implica rechazo; nunca recorte ni rellene valores.

Considere la criptografía una parte de la aceptación

Un HMAC coincidente demuestra que el emisor conoce el secreto, pero no que el mensaje sea reciente ni único. Aplique la tolerancia de fecha recomendada, registre identificadores ya aceptados y haga idempotente el procesamiento. Rote secretos con el solapamiento documentado. Rechace antes de encolar trabajo y devuelva un error genérico. Registre solo códigos seguros y pruebe cuerpos alterados, fechas caducadas, cabeceras inválidas, secretos erróneos y eventos repetidos. Separe además el fallo de autenticación del procesamiento funcional: ninguna tarea, escritura ni respuesta específica del evento debe comenzar antes de completar todas las comprobaciones. Para facilitar auditorías sin exponer credenciales, conserve únicamente un identificador de correlación, el nombre del proveedor y un motivo de rechazo no sensible.

Qué puede hacer con ella

Implementar un endpoint webhook nuevo

Convierta el algoritmo y la cabecera del proveedor en una lista revisable antes de programar.

Revisar una integración existente

Compruebe que la captura, el HMAC, la comparación segura y la defensa antirrepetición estén ordenados.

Preparar pruebas de seguridad

Defina casos negativos para cabeceras ausentes, cuerpos alterados, firmas inválidas, fechas vencidas y repeticiones.

Preguntas frecuentes

¿Esta herramienta verifica un webhook real?

No. Produce pasos de implementación y nunca solicita cuerpo, secreto ni firma.

¿Qué algoritmos reconoce?

HMAC-SHA1, HMAC-SHA256, HMAC-SHA384 y HMAC-SHA512. Cualquier otro genera un error de entrada.

¿Por qué debo conservar el cuerpo sin procesar?

Interpretarlo y serializarlo de nuevo puede cambiar sus bytes e invalidar una firma correcta.

¿Un HMAC válido evita las repeticiones?

No. Valide la fecha firmada y deduplique identificadores cuando el proveedor los facilite.

¿Debo enviar el secreto webhook?

No. Solo hacen falta el algoritmo y la cabecera; conserve el secreto en su entorno protegido.

¿Cuánto cuesta una solicitud API?

Cada solicitud API cuesta $0.002. La implementación determinista puede ejecutarse en el navegador sin enviar secretos.

Para desarrolladores — acceso por API

Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.

Endpoint de API

POSThttps://api.kit.forhosting.com/security/webhook-signature-verify-steps

¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, por email y desde Telegram — y pronto también desde nuestra app.

Llámela desde su stack

curl -X POST https://api.kit.forhosting.com/security/webhook-signature-verify-steps \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}'

const res = await fetch("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/security/webhook-signature-verify-steps",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/security/webhook-signature-verify-steps", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Ejemplo de solicitud

{
  "algorithm": "HMAC-SHA256",
  "header_name": "X-Webhook-Signature"
}

Ejemplo de respuesta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "security.webhook_signature_verify_steps",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.

Precio

Por solicitud$0.002

Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.

Errores

HTTP	Código	Significado
`401`	`unauthorized`	API key ausente o inválida.
`402`	`insufficient_balance`	El saldo no cubre el precio de la tarea.
`404`	`unknown_type`	El tipo de tarea no existe.
`429`	`rate_limited`	Demasiadas peticiones. Use el webhook en vez de sondear.

Ver la documentación completa del KIT →