Verificación de Firma

Cada entrega de webhook incluye una firma criptográfica para que pueda verificar que la solicitud proviene de MailLand y no fue manipulada durante el tránsito. Verifique siempre las firmas en producción.

Cómo Funciona la FirmaCopiar enlace de la sección

MailLand firma cada carga útil de webhook usando HMAC-SHA256 con la clave secreta de su webhook. La firma se incluye en el encabezado X-MLND-Signature.

Formato de la firma:

X-MLND-Signature: t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

Carga útil firmada:

{timestamp}.{raw_json_body}

La firma se calcula sobre la marca de tiempo concatenada con un punto y el cuerpo JSON sin procesar de la solicitud.

Ejemplo resueltoCopiar enlace de la sección

Compruebe su implementación con estos valores exactos antes de pasar a producción. Todo lo de abajo es real: la firma es la que MailLand produce para este secreto, esta marca de tiempo y este cuerpo.

Cadena firmada: la marca de tiempo, un punto literal y luego el cuerpo tal cual:

1708171200.{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}

HMAC-SHA256 de esa cadena, con el secreto como clave, en hexadecimal minúscula:

b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

Por lo tanto, el encabezado de esta entrega sería:

X-MLND-Signature: t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67

Reprodúzcala en una sola línea:

printf '%s' '1708171200.{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}' \
  | openssl dgst -sha256 -hmac 'whsec_docs_example_secret_do_not_use'

La marca de tiempo de este ejemplo está en el pasado, por lo que un verificador real la rechazaría por tolerancia. Pruebe primero el HMAC con la comprobación de tiempo desactivada y vuelva a activarla después.

Encabezados EnviadosCopiar enlace de la sección

Cada entrega de webhook incluye estos encabezados:

Otros dos encabezados son condicionales según el evento al que te suscribiste:

X-MLND-Message-Id no se envía actualmente en las entregas de message.*. Use el campo data.message_id del payload del evento en su lugar.

Pasos de VerificaciónCopiar enlace de la sección

signed_payload = timestamp + "." + raw_body

Ejemplos de CódigoCopiar enlace de la sección

#!/usr/bin/env bash
# Compute and verify an HMAC-SHA256 webhook signature using openssl

SIGNATURE_HEADER="t=1708171200,v1=b9f747ea899eafe911777060ca8f3c90828d37f1e16ee6e9ee98dacf8b316b67"
RAW_BODY='{"event":"message.delivered","event_id":"evt_a1b2c3d4e5f6"}'
SECRET="whsec_docs_example_secret_do_not_use"
TOLERANCE=300

# Parse timestamp and signature from header
TIMESTAMP=$(echo "$SIGNATURE_HEADER" | grep -oP '(?<=t=)[^,]+')
RECEIVED_SIG=$(echo "$SIGNATURE_HEADER" | grep -oP '(?<=v1=).+')

# Check timestamp tolerance
NOW=$(date +%s)
DIFF=$(( NOW - TIMESTAMP ))
if [ "${DIFF#-}" -gt "$TOLERANCE" ]; then
  echo "Error: Timestamp outside tolerance window" >&2
  exit 1
fi

# Compute expected signature
SIGNED_PAYLOAD="${TIMESTAMP}.${RAW_BODY}"
EXPECTED=$(printf '%s' "$SIGNED_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Compare signatures
if [ "$EXPECTED" = "$RECEIVED_SIG" ]; then
  echo "Signature valid"
else
  echo "Signature invalid" >&2
  exit 1
fi

Prevención de Ataques de RepeticiónCopiar enlace de la sección

La marca de tiempo en el encabezado de la firma previene los ataques de repetición. Si un atacante captura una entrega de webhook válida y la reenvía posteriormente, la verificación de la marca de tiempo la rechazará.

La tolerancia predeterminada de MailLand es de 5 minutos (300 segundos). Puede ajustar esto en su código de verificación, pero manténgalo lo suficientemente corto para prevenir ataques de repetición significativos.

Además, cada evento tiene un event_id único (en el encabezado X-MLND-Event-Id). Almacene los IDs de eventos procesados y rechace los duplicados para una protección adicional.

Toda entrega está firmadaCopiar enlace de la sección

No existe una ruta de entrega sin firmar. Si un webhook no tiene un secreto de firma utilizable, MailLand hace fallar la entrega y registra el fallo en lugar de enviar la carga útil sin un encabezado X-MLND-Signature: así que una firma faltante nunca es algo que su verificador deba tolerar. Rechace cualquier solicitud que no lleve una.

Regeneración de SecretosCopiar enlace de la sección

Si sospecha que el secreto de su webhook ha sido comprometido:

1. Llame a POST /v1/webhooks/{id}/regenerate-secret para obtener un nuevo secreto
2. Actualice el código de verificación de su servidor con el nuevo secreto
3. El secreto antiguo se invalida inmediatamente

Errores ComunesCopiar enlace de la sección

• Analizar el cuerpo como JSON antes de verificar: la firma se calcula sobre los bytes sin procesar, no sobre un objeto JSON re-serializado. Verifique primero, luego analice.
• Usar comparación de cadenas en lugar de comparación de tiempo constante: la comparación de cadenas ordinaria es vulnerable a ataques de temporización.
• Ignorar la marca de tiempo: sin validación de la marca de tiempo, las cargas útiles capturadas pueden reproducirse indefinidamente.
• Codificar el secreto de forma fija: utilice variables de entorno o un administrador de secretos.

Próximos PasosCopiar enlace de la sección

• Lógica de reintentos: comprenda el comportamiento de reintento y el manejo de errores
• Eventos: referencia completa de tipos de eventos
• Descripción general de webhooks: cree y administre webhooks