Firma de Solicitudes

Cada solicitud de webhook de Emailit incluye un encabezado X-Emailit-Signature que contiene una firma HMAC-SHA256 y un encabezado X-Emailit-Timestamp con la marca de tiempo Unix de cuando se firmó la solicitud. Debes verificar esta firma para asegurar que la solicitud es auténtica y no ha sido alterada.

Cómo funciona

Cuando creas un webhook, Emailit genera un secreto de firma para ese endpoint
Para cada entrega, Emailit concatena la marca de tiempo y el cuerpo de la solicitud sin procesar como {timestamp}.{rawBody}
Se calcula un hash HMAC-SHA256 sobre esa cadena usando tu secreto de firma
La firma se envía en el encabezado X-Emailit-Signature y la marca de tiempo en X-Emailit-Timestamp
Tu servidor recalcula la firma y la compara con el valor del encabezado

Verificación de la firma

Para verificar una firma de webhook:

Extrae los encabezados X-Emailit-Signature y X-Emailit-Timestamp de la solicitud
Concatena la marca de tiempo y el cuerpo de la solicitud sin procesar como {timestamp}.{rawBody}
Calcula un hash HMAC-SHA256 de esa cadena usando tu secreto de firma del webhook
Compara el hash calculado con la firma usando una comparación segura contra ataques de temporización
Opcionalmente, rechaza solicitudes donde la marca de tiempo sea anterior a unos minutos para protegerte contra ataques de repetición

import crypto from 'crypto';

function verifyWebhookSignature(rawBody, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${rawBody}`;
  const computed = crypto
    .createHmac('sha256', secret)
    .update(signedPayload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// En tu manejador de webhook:
const rawBody = req.body; // cuerpo de solicitud sin procesar como string
const signature = req.headers['x-emailit-signature'];
const timestamp = req.headers['x-emailit-timestamp'];
const secret = process.env.WEBHOOK_SIGNING_SECRET;

// Protección contra ataques de repetición (tolerancia de 5 minutos)
const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
if (age > 300) {
  return res.status(401).send('Solicitud demasiado antigua');
}

if (!verifyWebhookSignature(rawBody, signature, timestamp, secret)) {
  return res.status(401).send('Firma inválida');
}

import hmac
import hashlib
import time

def verify_webhook_signature(raw_body, signature, timestamp, secret):
    signed_payload = f"{timestamp}.{raw_body}"
    computed = hmac.new(
        secret.encode('utf-8'),
        signed_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed, signature)

# Protección contra ataques de repetición (tolerancia de 5 minutos)
age = int(time.time()) - int(timestamp)
if age > 300:
    raise ValueError("Solicitud demasiado antigua")

function verifyWebhookSignature(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret
): bool {
    $signedPayload = "{$timestamp}.{$rawBody}";
    $computed = hash_hmac('sha256', $signedPayload, $secret);
    return hash_equals($computed, $signature);
}

// Protección contra ataques de repetición (tolerancia de 5 minutos)
$age = time() - intval($timestamp);
if ($age > 300) {
    http_response_code(401);
    exit('Solicitud demasiado antigua');
}

require 'openssl'

def verify_webhook_signature(raw_body, signature, timestamp, secret)
  signed_payload = "#{timestamp}.#{raw_body}"
  computed = OpenSSL::HMAC.hexdigest('SHA256', secret, signed_payload)
  Rack::Utils.secure_compare(computed, signature)
end

# Protección contra ataques de repetición (tolerancia de 5 minutos)
age = Time.now.to_i - timestamp.to_i
raise 'Solicitud demasiado antigua' if age > 300

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
    "strconv"
)

func verifyWebhookSignature(rawBody, signature, timestamp, secret string) bool {
    signedPayload := fmt.Sprintf("%s.%s", timestamp, rawBody)
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signedPayload))
    computed := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(computed), []byte(signature))
}

// Protección contra ataques de repetición (tolerancia de 5 minutos)
ts, _ := strconv.ParseInt(timestamp, 10, 64)
if time.Now().Unix()-ts > 300 {
    // rechazar solicitud
}

Verificar firma

import crypto from 'crypto';

function verifyWebhookSignature(rawBody, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${rawBody}`;
  const computed = crypto
    .createHmac('sha256', secret)
    .update(signedPayload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// En tu manejador de webhook:
const rawBody = req.body; // cuerpo de solicitud sin procesar como string
const signature = req.headers['x-emailit-signature'];
const timestamp = req.headers['x-emailit-timestamp'];
const secret = process.env.WEBHOOK_SIGNING_SECRET;

// Protección contra ataques de repetición (tolerancia de 5 minutos)
const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
if (age > 300) {
  return res.status(401).send('Solicitud demasiado antigua');
}

if (!verifyWebhookSignature(rawBody, signature, timestamp, secret)) {
  return res.status(401).send('Firma inválida');
}

Notas importantes

La firma se calcula sobre {timestamp}.{rawBody} — siempre usa el cuerpo de la solicitud sin procesar como string, no una versión re-serializada (ej. JSON.stringify(req.body)). Las diferencias en espacios en blanco o el orden de las claves romperán la firma.
Siempre usa una función de comparación segura contra ataques de temporización (ej. crypto.timingSafeEqual, hmac.compare_digest, hash_equals) para prevenir ataques de temporización.
Considera rechazar solicitudes donde el X-Emailit-Timestamp sea anterior a unos minutos para protegerte contra ataques de repetición.
Mantén tu secreto de firma seguro — guárdalo en variables de entorno, no en el código fuente.
Puedes encontrar tu secreto de firma del webhook en el panel de Emailit bajo la configuración de webhooks, o a través de la API de Webhooks.

PreviousSolicitudes de Webhook

Nextemail.accepted