Підпис запиту

Кожен webhook-запит від Emailit містить заголовок X-Emailit-Signature з підписом HMAC-SHA256 та заголовок X-Emailit-Timestamp з Unix-часовою міткою моменту підписання запиту. Вам слід перевіряти цей підпис, щоб переконатися в автентичності запиту та відсутності втручання в його зміст.

Як це працює

При створенні webhook’а Emailit генерує секретний ключ підпису для цієї кінцевої точки
Для кожної доставки Emailit об’єднує часову мітку та необроблене тіло запиту у форматі {'{'}timestamp{'}'}.{'{'}rawBody{'}'}
Обчислюється HMAC-SHA256 хеш цього рядка з використанням вашого секретного ключа підпису
Підпис надсилається в заголовку X-Emailit-Signature, а часова мітка — в X-Emailit-Timestamp
Ваш сервер повторно обчислює підпис і порівнює його зі значенням у заголовку

Перевірка підпису

Для перевірки підпису webhook’а:

Витягніть заголовки X-Emailit-Signature та X-Emailit-Timestamp із запиту
Об’єднайте часову мітку та необроблене тіло запиту у форматі {'{'}timestamp{'}'}.{'{'}rawBody{'}'}
Обчисліть HMAC-SHA256 хеш цього рядка, використовуючи ваш секретний ключ підпису webhook’а
Порівняйте обчислений хеш з підписом, використовуючи безпечне порівняння за часом
За бажанням відхиляйте запити, де часова мітка старша за кілька хвилин, щоб захиститися від атак повторного відтворення

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')
);
}

// У вашому обробнику webhook'а:
const rawBody = req.body; // необроблене тіло запиту як рядок
const signature = req.headers['x-emailit-signature'];
const timestamp = req.headers['x-emailit-timestamp'];
const secret = process.env.WEBHOOK_SIGNING_SECRET;

// Захист від атак повторного відтворення (толерантність 5 хвилин)
const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
if (age > 300) {
return res.status(401).send('Запит занадто старий');
}

if (!verifyWebhookSignature(rawBody, signature, timestamp, secret)) {
return res.status(401).send('Недійсний підпис');
}

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)

# Захист від атак повторного відтворення (толерантність 5 хвилин)
age = int(time.time()) - int(timestamp)
if age > 300:
raise ValueError("Запит занадто старий")

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);
}

// Захист від атак повторного відтворення (толерантність 5 хвилин)
$age = time() - intval($timestamp);
if ($age > 300) {
http_response_code(401);
exit('Запит занадто старий');
}

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

# Захист від атак повторного відтворення (толерантність 5 хвилин)
age = Time.now.to_i - timestamp.to_i
raise 'Запит занадто старий' 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))
}

// Захист від атак повторного відтворення (толерантність 5 хвилин)
ts, _ := strconv.ParseInt(timestamp, 10, 64)
if time.Now().Unix()-ts > 300 {
// відхилити запит
}

Важливі зауваження

Підпис обчислюється для {'{'}timestamp{'}'}.{'{'}rawBody{'}'} — завжди використовуйте необроблений рядок тіла запиту, а не повторно серіалізовану версію (наприклад, JSON.stringify(req.body)). Відмінності в пробілах або порядку ключів порушать підпис.
Завжди використовуйте функцію безпечного порівняння за часом (наприклад, crypto.timingSafeEqual, hmac.compare_digest, hash_equals) для запобігання атакам за часом.
Розгляньте можливість відхилення запитів, де X-Emailit-Timestamp старший за кілька хвилин, щоб захиститися від атак повторного відтворення.
Тримайте ваш секретний ключ підпису в безпеці — зберігайте його в змінних середовища, а не в вихідному коді.
Ви можете знайти ваш секретний ключ підпису webhook’а в панелі керування Emailit у налаштуваннях webhook’а або через API Webhooks.

Підпис запиту

Як це працює

Перевірка підпису

Важливі зауваження

Локалізовано за допомогою ШІ