Firmar y verificar webhooks

El problema de un webhook sin firma

Un endpoint que acepta cualquier cuerpo POST como verdadero es un endpoint que cualquiera puede suplantar: un falso evento de pago exitoso, una actualización de pedido falsificada, una solicitud reproducida a partir de un payload capturado. Y del lado de quien envía, sin una firma que mostrar, un socio puede negar que usted haya enviado un evento, dejando un ticket de soporte sin forma de resolverse. dev.webhook_sign existe porque 'confiar en el payload' dejó de ser un modelo de seguridad viable en el momento en que los webhooks se volvieron infraestructura crítica.

Dos direcciones, un solo endpoint

Envíe POST a /dev/webhook-sign con un payload y la intención de firmarlo, y la tarea devuelve una firma que usted adjunta a los encabezados de la solicitud saliente antes de entregarla. Envíe al mismo endpoint un payload entrante junto con la firma recibida y la intención de verificarlo, y este revisa la firma contra el payload e informa si es válida, si fue alterada o si expiró. En ambos casos recibe un task_id de inmediato, y el resultado —una firma o un veredicto de verificación— llega por webhook firmado o mediante un enlace firmado válido por 24 horas.

Por qué firmar no es lo mismo que cifrar

Una firma no oculta el payload; demuestra quién lo envió y que no cambió después de firmarse, usando un secreto compartido o un par de claves junto con un hash del contenido del mensaje. Es el mismo principio detrás de los webhooks firmados con HMAC que las plataformas más grandes han usado durante más de una década: quien recibe recalcula la firma a partir del payload crudo y la compara con la que llegó, y cualquier discrepancia significa que algo se alteró, que se excedió una ventana de tiempo, o que en realidad nunca lo envió quien dice haberlo hecho.

Cómo encaja la verificación en un flujo real

Un receptor de webhooks que verifica antes de procesar cierra toda una categoría de intentos de suplantación sin agregar una latencia relevante, ya que la verificación misma es rápida y se cobra a una tarifa plana de $0.002 por solicitud sin costo alguno cuando falla. Los equipos que manejan muchas integraciones de webhooks suelen dirigir cada payload entrante a través de la verificación como primer paso automatizado, rechazando lo que no pasa la revisión antes de que llegue a la lógica de negocio; aplicar esa misma disciplina del lado saliente significa que cada socio que recibe sus webhooks puede confirmar por sí mismo que realmente vienen de usted.