Guía práctica
Verificar las firmas de los webhooks
Comprueba que las peticiones de webhook vienen de Emailit verificando la firma HMAC-SHA256 y la marca de tiempo, con código para Node.js, Python, PHP, Ruby, Go y Laravel.
Cualquiera que conozca la URL de tu webhook puede enviarle peticiones. Cada petición de Emailit se firma con el secreto de tu webhook, así que verificar la firma demuestra que la petición viene de Emailit y que no se ha modificado por el camino. Comprobar la marca de tiempo impide, además, que se reutilicen peticiones antiguas. Haz ambas cosas antes de actuar sobre cualquier evento.
Cómo funciona la firma
Cada webhook tiene su propio secreto: whsec_ seguido de 64 caracteres hexadecimales. Lo ves una sola vez, al crear el webhook o restablecer el secreto, y Obtener un webhook lo devuelve.
En cada petición, Emailit:
- Toma la hora Unix actual en segundos, por ejemplo
1790846045, y la envía enX-Emailit-Timestamp. - Construye la cadena
{timestamp}.{raw body}: la marca de tiempo, un punto y los bytes exactos del cuerpo de la petición. - Calcula el HMAC-SHA256 de esa cadena con el secreto completo, incluido
whsec_, como clave. - Envía el resultado, codificado en hexadecimal y en minúsculas, en
X-Emailit-Signature.
Para verificarla, tu endpoint repite los pasos 2 y 3 con el cuerpo en bruto que recibió y compara su resultado con la cabecera mediante una comparación en tiempo constante. Después comprueba que la marca de tiempo es reciente. Te recomendamos una tolerancia de 5 minutos (300 segundos). Cada reintento se vuelve a firmar con una marca de tiempo nueva, así que un margen de 5 minutos no rechaza los reintentos.
Verificar las peticiones
Cada ejemplo lee el cuerpo en bruto, rechaza con 401 las peticiones sin firma, con una firma antigua o con una firma incorrecta, y solo entonces analiza el array JSON.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.EMAILIT_WEBHOOK_SECRET; // full value, including whsec_
const TOLERANCE_SECONDS = 300;
export function verifyEmailitSignature(rawBody, signature, timestamp) {
if (!signature || !timestamp) return false;
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!(age <= TOLERANCE_SECONDS)) return false; // also rejects non-numeric timestamps
const expected = crypto
.createHmac('sha256', SECRET)
.update(`${timestamp}.`)
.update(rawBody) // a Buffer with the exact bytes received
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// express.raw() keeps the body as a Buffer. Don't run express.json() on this route.
app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyEmailitSignature(
req.body,
req.get('X-Emailit-Signature'),
req.get('X-Emailit-Timestamp'),
);
if (!valid) return res.status(401).send('Invalid signature');
const events = JSON.parse(req.body.toString('utf8'));
// Queue the events for processing, then acknowledge.
res.sendStatus(204);
});
app.listen(3000);import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["EMAILIT_WEBHOOK_SECRET"].encode() # full value, including whsec_
TOLERANCE_SECONDS = 300
def verify_emailit_signature(raw_body: bytes, signature: str | None, timestamp: str | None) -> bool:
if not signature or not timestamp:
return False
try:
age = abs(time.time() - int(timestamp))
except ValueError:
return False
if age > TOLERANCE_SECONDS:
return False
expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
@app.post("/webhooks/emailit")
def emailit_webhook():
raw_body = request.get_data() # raw bytes; don't use request.json first
if not verify_emailit_signature(
raw_body,
request.headers.get("X-Emailit-Signature"),
request.headers.get("X-Emailit-Timestamp"),
):
abort(401)
events = json.loads(raw_body)
# Queue the events for processing, then acknowledge.
return "", 204<?php
const TOLERANCE_SECONDS = 300;
function verifyEmailitSignature(string $rawBody, string $signature, string $timestamp, string $secret): bool
{
if ($signature === '' || !ctype_digit($timestamp)) {
return false;
}
if (abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
return false;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EMAILIT_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_EMAILIT_TIMESTAMP'] ?? '';
$secret = (string) getenv('EMAILIT_WEBHOOK_SECRET'); // full value, including whsec_
if (!verifyEmailitSignature($rawBody, $signature, $timestamp, $secret)) {
http_response_code(401);
exit('Invalid signature');
}
$events = json_decode($rawBody, true);
// Queue the events for processing, then acknowledge.
http_response_code(204);require 'sinatra'
require 'openssl'
require 'json'
require 'rack/utils'
SECRET = ENV.fetch('EMAILIT_WEBHOOK_SECRET') # full value, including whsec_
TOLERANCE_SECONDS = 300
def verify_emailit_signature(raw_body, signature, timestamp)
return false if signature.to_s.empty? || timestamp.to_s !~ /\A\d+\z/
return false if (Time.now.to_i - timestamp.to_i).abs > TOLERANCE_SECONDS
expected = OpenSSL::HMAC.hexdigest('SHA256', SECRET, "#{timestamp}.#{raw_body}")
Rack::Utils.secure_compare(expected, signature)
end
post '/webhooks/emailit' do
raw_body = request.body.read # in Rails, use request.raw_post
valid = verify_emailit_signature(
raw_body,
request.env['HTTP_X_EMAILIT_SIGNATURE'],
request.env['HTTP_X_EMAILIT_TIMESTAMP']
)
halt 401, 'Invalid signature' unless valid
events = JSON.parse(raw_body)
# Queue the events for processing, then acknowledge.
status 204
endpackage main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"net/http"
"os"
"strconv"
"time"
)
const toleranceSeconds = 300
func verifyEmailitSignature(rawBody []byte, signature, timestamp, secret string) bool {
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || signature == "" {
return false
}
age := time.Now().Unix() - ts
if age > toleranceSeconds || age < -toleranceSeconds {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp + "."))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signature))
}
type Event struct {
EventID string `json:"event_id"`
Type string `json:"type"`
Data json.RawMessage `json:"data"`
}
func emailitWebhook(w http.ResponseWriter, r *http.Request) {
rawBody, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "cannot read body", http.StatusBadRequest)
return
}
secret := os.Getenv("EMAILIT_WEBHOOK_SECRET") // full value, including whsec_
if !verifyEmailitSignature(rawBody, r.Header.Get("X-Emailit-Signature"), r.Header.Get("X-Emailit-Timestamp"), secret) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var events []Event
if err := json.Unmarshal(rawBody, &events); err != nil {
http.Error(w, "invalid JSON", http.StatusBadRequest)
return
}
// Queue the events for processing, then acknowledge.
w.WriteHeader(http.StatusNoContent)
}
func main() {
http.HandleFunc("/webhooks/emailit", emailitWebhook)
http.ListenAndServe(":8080", nil)
}<?php
// config/services.php: 'emailit' => ['webhook_secret' => env('EMAILIT_WEBHOOK_SECRET')],
// routes/api.php: Route::post('/webhooks/emailit', EmailitWebhookController::class);
namespace App\Http\Controllers;
use App\Jobs\ProcessEmailitEvent;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
class EmailitWebhookController extends Controller
{
private const TOLERANCE_SECONDS = 300;
public function __invoke(Request $request): Response
{
$rawBody = $request->getContent();
$signature = (string) $request->header('X-Emailit-Signature', '');
$timestamp = (string) $request->header('X-Emailit-Timestamp', '');
$secret = (string) config('services.emailit.webhook_secret'); // full value, including whsec_
$fresh = ctype_digit($timestamp)
&& abs(time() - (int) $timestamp) <= self::TOLERANCE_SECONDS;
$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
abort_unless($fresh && hash_equals($expected, $signature), 401, 'Invalid signature');
foreach (json_decode($rawBody, true) as $event) {
ProcessEmailitEvent::dispatch($event); // a queued job
}
return response()->noContent();
}
}En Laravel, las rutas de routes/api.php no se comprueban con tokens CSRF y reciben el prefijo /api, así que la URL del ejemplo es https://acme.com/api/webhooks/emailit. Si registras la ruta en routes/web.php, exclúyela de la verificación CSRF o Laravel rechazará las peticiones de Emailit con 419.
Probar tu verificación
Comprueba tu función con este ejemplo conocido antes de desplegar. Llama directamente a la parte del HMAC, porque la marca de tiempo está en el pasado y no supera la comprobación de 5 minutos.
| Entrada | Valor |
|---|---|
| Secreto | whsec_4f2a9c1e7b3d5a8f0e6c2b9d4a7f1e3c5b8d0a2f6e9c3b7d1a5f8e2c4b6d9a0f |
| Marca de tiempo | 1790846045 |
| Firma esperada | 7242b580f77ec488f8ac21b57f092e3db61a431694f13074c7b4c85a4dd04be3 |
Cuerpo en bruto, exactamente como aparece, sin salto de línea al final:
[{"event_id":"evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP","type":"email.delivered"}]Después, usa Send test en el webhook para confirmar que tu endpoint desplegado acepta una petición firmada real. Consulta Configurar un webhook.
Errores habituales
- Analizar antes de verificar. Los frameworks que analizan el JSON automáticamente (
express.json(),request.jsonen Flask, los params de Rails) te dan un objeto, no los bytes que firmó Emailit. Lee el cuerpo en bruto en la ruta del webhook. - Volver a serializar el JSON.
JSON.stringify(req.body)ojson.dumps(data)generan espacios, orden de claves o escapes distintos, así que el HMAC no coincidirá. Calcula siempre el hash del cuerpo exactamente como se recibió. - Modificar el secreto. Usa el valor completo, incluido
whsec_, como texto plano. No quites el prefijo ni lo decodifiques como hexadecimal o Base64. - Firmar la cadena equivocada. La entrada es la marca de tiempo, un punto y después el cuerpo. Si firmas solo el cuerpo o unes las partes con otro separador, la verificación falla.
- Usar
==para comparar. Usa una función de tiempo constante comocrypto.timingSafeEqual,hmac.compare_digest,hash_equals,Rack::Utils.secure_compareohmac.Equal. - Un reloj del servidor desajustado. Si el reloj de tu servidor se desvía, las peticiones válidas quedan fuera de la tolerancia. Mantenlo sincronizado con NTP.
- Un secreto antiguo o que no corresponde. Tras Reset, el secreto anterior deja de funcionar de inmediato, también para los reintentos. Cada webhook tiene su propio secreto, así que dos endpoints no pueden compartir uno.
- Un middleware que reescribe el cuerpo. Los proxies, las pasarelas de API o la descompresión del cuerpo que cambian los bytes antes de que los vea tu código rompen la firma. Verifica lo más cerca posible de la petición en bruto.
Las peticiones que no superan la verificación reciben un 401 de tu endpoint y se reintentan como cualquier otro fallo, así que, si corriges un secreto mal configurado en unas pocas horas, no pierdes nada.