PHP Webhooks empfangen und validieren

Webhooks sind HTTP-Callbacks die ein Dienst aufruft wenn etwas passiert.
GitHub schickt einen beim Push, Stripe bei einer Zahlung, Telegram bei einer Nachricht.
Das Empfangen ist einfach, die Signatur zu prüfen ist wichtig.

Grundstruktur

<?php

// Keine HTML-Ausgabe, keine Session
header('Content-Type: application/json');

$payload = file_get_contents('php://input');
$data    = json_decode($payload, true);

if (!$data) {
    http_response_code(400);
    exit;
}

// Verarbeitung
processWebhook($data);

http_response_code(200);
echo json_encode(['ok' => true]);

GitHub-Signatur prüfen

GitHub signiert jeden Webhook mit einem HMAC-SHA256 über den Payload-Body.

function verifyGithubSignature(string $payload, string $secret): bool
{
    $signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
    $expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

$secret  = 'mein-webhook-secret';
$payload = file_get_contents('php://input');

if (!verifyGithubSignature($payload, $secret)) {
    http_response_code(403);
    exit;
}

hash_equals statt === verhindert Timing-Angriffe.

Sofort antworten, dann verarbeiten

Webhooks haben oft kurze Timeouts. Wenn die Verarbeitung länger dauert sofort 200 zurückgeben und dann weiterarbeiten.

// Sofort antworten
http_response_code(200);
echo json_encode(['ok' => true]);

// Ausgabe-Puffer flushen und Verbindung schließen
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

// Jetzt die eigentliche Arbeit tun
processWebhook($data);