# Webhook-Signaturen verifizieren

> Prüfen Sie, ob Webhook-Anfragen von Emailit stammen, indem Sie die HMAC-SHA256-Signatur und den Zeitstempel verifizieren, mit Code für Node.js, Python, PHP, Ruby, Go und Laravel.

Wer Ihre Webhook-URL kennt, kann Anfragen an sie senden. Jede Anfrage von Emailit ist mit dem Secret Ihres Webhooks signiert; die Verifizierung der Signatur belegt daher, dass die Anfrage von Emailit stammt und unterwegs nicht verändert wurde. Die Prüfung des Zeitstempels verhindert außerdem, dass alte Anfragen erneut eingespielt werden. Tun Sie beides, bevor Sie auf ein Event reagieren.

## So funktioniert die Signatur

Jeder Webhook hat sein eigenes Secret: `whsec_`, gefolgt von 64 Hexadezimalzeichen. Sie sehen es einmal, wenn Sie den Webhook erstellen oder das Secret zurücksetzen, und [Webhook abrufen](/de/docs/api-reference/webhooks/get/) gibt es zurück.

Für jede Anfrage geht Emailit so vor:

1. Es nimmt die aktuelle Unix-Zeit in Sekunden, zum Beispiel `1790846045`, und sendet sie in `X-Emailit-Timestamp`.
2. Es bildet den String `{timestamp}.{raw body}`: den Zeitstempel, einen Punkt und die exakten Bytes des Anfrage-Bodys.
3. Es berechnet den HMAC-SHA256 dieses Strings mit dem vollständigen Secret, einschließlich `whsec_`, als Schlüssel.
4. Es sendet das Ergebnis, hexadezimal kodiert in Kleinbuchstaben, in `X-Emailit-Signature`.

Zur Verifizierung wiederholt Ihr Endpunkt die Schritte 2 und 3 mit dem unveränderten Body, den er erhalten hat, und vergleicht sein Ergebnis per Vergleich in konstanter Zeit mit dem Header. Anschließend prüft er, ob der Zeitstempel aktuell ist. Wir empfehlen eine Toleranz von 5 Minuten (300 Sekunden). Jede Wiederholung wird mit einem neuen Zeitstempel erneut signiert, daher lehnt ein Zeitfenster von 5 Minuten keine Wiederholungen ab.

## Anfragen verifizieren

Jedes Beispiel liest den unveränderten Body, lehnt Anfragen mit fehlender, veralteter oder falscher Signatur mit `401` ab und parst erst dann das JSON-Array.

**Node.js**

```javascript title="server.js"
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);
```

**Python**

```python title="app.py"
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**

```php title="webhook.php"
<?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);
```

**Ruby**

```ruby title="app.rb"
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
end
```

**Go**

```go title="main.go"
package 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)
}
```

**Laravel**

```php title="app/Http/Controllers/EmailitWebhookController.php"
<?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();
    }
}
```

In Laravel werden Routen in `routes/api.php` nicht auf CSRF-Tokens geprüft und erhalten das Präfix `/api`, daher lautet die URL oben `https://acme.com/api/webhooks/emailit`. Wenn Sie die Route in `routes/web.php` registrieren, nehmen Sie den Pfad von der CSRF-Prüfung aus, sonst lehnt Laravel die Anfragen von Emailit mit `419` ab.

## Verifizierung testen

Prüfen Sie Ihre Funktion mit diesem bekannten Beispiel, bevor Sie sie bereitstellen. Rufen Sie den HMAC-Teil direkt auf, weil der Zeitstempel in der Vergangenheit liegt und die 5-Minuten-Prüfung nicht besteht.

| Eingabe | Wert |
| --- | --- |
| Secret | `whsec_4f2a9c1e7b3d5a8f0e6c2b9d4a7f1e3c5b8d0a2f6e9c3b7d1a5f8e2c4b6d9a0f` |
| Zeitstempel | `1790846045` |
| Erwartete Signatur | `7242b580f77ec488f8ac21b57f092e3db61a431694f13074c7b4c85a4dd04be3` |

Unveränderter Body, genau wie gezeigt, ohne abschließenden Zeilenumbruch:

```json
[{"event_id":"evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP","type":"email.delivered"}]
```

Prüfen Sie dann mit **Send test** am Webhook, ob Ihr bereitgestellter Endpunkt eine echte signierte Anfrage annimmt. Siehe [Webhook einrichten](/de/docs/webhooks/set-up/#send-a-test-event).

## Häufige Fehler

- **Parsen vor dem Verifizieren.** Frameworks, die JSON automatisch parsen (`express.json()`, `request.json` in Flask, Rails-Params), liefern Ihnen ein Objekt, nicht die Bytes, die Emailit signiert hat. Lesen Sie auf der Webhook-Route den unveränderten Body.
- **Erneutes Serialisieren des JSON.** `JSON.stringify(req.body)` oder `json.dumps(data)` erzeugt andere Leerzeichen, eine andere Schlüsselreihenfolge oder ein anderes Escaping, sodass der HMAC nicht übereinstimmt. Hashen Sie den Body immer genau so, wie Sie ihn erhalten haben.
- **Verändern des Secrets.** Verwenden Sie den gesamten Wert, einschließlich `whsec_`, als Klartext. Entfernen Sie das Präfix nicht und dekodieren Sie den Wert weder hexadezimal noch per Base64.
- **Signieren des falschen Strings.** Die Eingabe ist der Zeitstempel, ein Punkt, dann der Body. Nur den Body zu signieren oder ein anderes Trennzeichen zu verwenden, schlägt fehl.
- **Vergleich mit `==`.** Verwenden Sie eine Funktion mit konstanter Laufzeit wie `crypto.timingSafeEqual`, `hmac.compare_digest`, `hash_equals`, `Rack::Utils.secure_compare` oder `hmac.Equal`.
- **Falsche Serveruhr.** Weicht die Uhr Ihres Servers ab, fallen gültige Anfragen aus der Toleranz. Halten Sie sie per NTP synchron.
- **Altes oder falsches Secret.** Nach **Reset** funktioniert das alte Secret sofort nicht mehr, auch nicht für Wiederholungen. Jeder Webhook hat sein eigenes Secret, daher können sich zwei Endpunkte keines teilen.
- **Middleware, die den Body umschreibt.** Proxys, API-Gateways oder eine Dekomprimierung des Bodys, die die Bytes verändern, bevor Ihr Code sie sieht, machen die Signatur ungültig. Verifizieren Sie so nah an der unveränderten Anfrage wie möglich.

Anfragen, deren Verifizierung fehlschlägt, erhalten von Ihrem Endpunkt ein `401` und werden wie jeder andere Fehlschlag [wiederholt](/de/docs/webhooks/retries-and-failures/); wenn Sie ein falsch konfiguriertes Secret innerhalb weniger Stunden korrigieren, geht also nichts verloren.

## Siehe auch

  - [Webhook-Anfragen](/de/docs/webhooks/webhook-requests/)
  - [Wiederholungen und Fehlschläge](/de/docs/webhooks/retries-and-failures/)

---
Quelle: https://emailit.com/de/docs/webhooks/request-signature/
