Sie haben ein Dienst, der reagieren muss, wenn etwas an einem anderen Ort passiert. Ein Zahlungsauftrag wird bearbeitet. Ein Kundenverzeichnis ändert sich. Ein Repository wird gepusht. Sie könnten ein API alle Minute abfragen und Zyklen verschwenden, indem Sie immer wieder 'Gibt es etwas Neues?' fragen, oder Sie lassen das Quellsystem Sie anrufen, wenn das Ereignis eintritt.
Dort enden die meisten Web Hook-Beispielartikel. Sie zeigen eine Route, drucken den JSON-Körper aus und kehren zurück 200und rufen Sie es dann ab. Diese Version funktioniert bis zu dem Moment, an dem jemand einen gefälschten Anforderung sendet, eine gültige wiederholt oder der Handler bricht, weil die Framework die Anforderung vor der Signaturprüfung verarbeitet hat.
Dieses Leitfaden nimmt den Weg, den Sie in der Produktion verwenden werden. Die Beispiele sind klein genug, um zu kopieren, aber sie enthalten die wichtigen Teile: die Behandlung des Rohkörpers, die HMAC-Verifizierung, die Überprüfung der Zeitstempel, die schnelle Bestätigung und die praktische Fehlerbehebung.
Inhaltsverzeichnis
- Was sind Webhooks und warum sollten Sie sie verwenden?
- Anatomie einer Webhook-HTTP-Anfrage
- Wie sicher Webhook-Signaturen verifizieren
- Schutz vor Wiedergabeangriffen
- Ein Webhook-Empfänger in Node.js erstellen
- Ein Webhook-Empfänger in Python erstellen
- Ein Beispiel für einen Webhook-Empfänger in Go
- Wichtige Debugging-Techniken
- Ein Checkliste für Webhooks, die für die Produktion bereit sind
- Häufig gestellte Fragen zu Webhooks
Was sind Webhooks und warum sollten Sie sie verwenden?
Ihr Rechnungsanbieter markiert eine Rechnung als bezahlt um 02:13. Wenn Ihre App um 02:14 davon erfährt, erhält der Kunde sofort Zugriff. Wenn Ihre App davon erst auf dem nächsten Polling-Zyklus erfährt, müssen sie warten, Support erhält eine Ticketanfrage und Ihre Protokolle füllen sich mit unnötigem Lärm. Webhooks lösen dieses Zeitungsproblem, indem sie einen HTTP-Aufruf senden, wenn das Ereignis eintritt.
In der Praxis ist ein Webhook ein Ereignis-getriebener POST von einem System zu einem anderen. Der Anbieter erkennt eine Änderung, wie z.B. invoice.paid, order.created oder push und sendet die Ereignisdaten an eine URL, die Sie kontrollieren. Das entfernt den ständigen "Gibt es etwas Neues?"-Zyklus, den Polling erzeugt und reduziert die Anzahl der verschwendeten Anfragen.
Dieses Muster tritt in realen Systemen auf, weil es sauber auf Geschäftsevents abbildet. Stripe sendet Zahlungsabschlüsse. GitHub sendet Repository-Aktivitäten. Shopify sendet Bestellaktualisierungen. Die Form ist einfach, aber die Produktionsverhalten ist nicht. Ein Webhook, der Geld, Zugriff oder Lagerbestände aktualisiert, verdient die gleiche Sorgfalt wie jeder öffentliche API-Endpunkt, insbesondere wenn sich Wiederholungen, Duplikate und unvertrauenswürdige Traffic einmischen.
Das mentale Modell, das hilft
Ein nützlicher Weg, ein Webhook-Fluss zu umschreiben, ist als vier Teile, die zusammenarbeiten:
- Quellensystem. Das Service, das den Ereignis detektiert.
- Zielendpunkt. Ihre HTTP-Routen, die es empfängt.
- Ereignis. Der benannte Änderung, der aufgetreten ist, wie
invoice.paidoderpush. - Payload. Der Anforderungskörper mit den Details, die Ihr code benötigt.
Der Anbieter sendet Fakten über etwas, das bereits passiert ist. Ihre Aufgabe ist es, den Absender zu überprüfen, die Anfrage als frisch zu bestätigen und die Änderung einmal anzuwenden. Die letzte Sache ist wichtiger als viele grundlegende Tutorials zugeben. In der Produktion ist die doppelte Lieferung normaler Verhalten, kein Randfall.
Praktische Regel: Verwenden Sie Webhooks für Ereignis-gesteuerte Aktualisierungen. Verwenden Sie Polling für geplante Lesen, Nachfüllungen oder Anbieter, die keine ausgehenden Ereignisse anbieten.
Für Teams, die breitere Workflow-Automatisierung und Datenintegration, werden Webhooks normalerweise die Ereignisschicht darstellen, die die Systeme ohne unnötigen Anfrageverkehr in Einklang bringt. Wenn Sie an Integrationsschwerpunkten arbeiten, sind Capgo’s Hintergrundentwicklungsartikel nützlich, weil sich die Kernprobleme um Wiederholungen, Warteschlangen, Beobachtbarkeit und Fehlerbehandlung drehen.
Was funktioniert und was scheitert in der Produktion
Die Konfigurationen, die gut funktionieren, sind normalerweise langweilig durch Design. Abonnieren Sie nur die Ereignisse, die Sie benötigen. Halten Sie Endpunkte durch Anbieter oder Ereignisfamilie skaliert. Speichern Sie Ereignis-IDs, damit doppelte Lieferungen keine Seitenwirkungen wiederholen. Gehen Sie mit einer schnellen 2xx-Antwort aus, sobald die Anfrage validiert und in die Warteschlange gelegt wurde, dann führen Sie die Geschäftslogik asynchron aus.
Die verletzliche Version ist leicht zu erkennen. Ein generischer Endpunkt handhabt alles. Die Signaturprüfungen werden während der frühen Testphase ausgelassen und kommen nie wieder zurück. Der Handler schreibt direkt in kritische Tabellen, bevor er überprüft, ob das Ereignis echt oder veraltet ist. Das funktioniert in einer Demo und scheitert bei Wiederholungsstürmen, Provider-Ausfällen oder einem Angreifer, der alte Anforderungen wiederholt.
Dieser Kompromiss definiert den Rest dieser Anleitung. Die 'Hallo-Welt'-Version eines Webhook-Empfängers ist klein. Die Produktionsfertige Version fügt die Signaturprüfung, die Wiederholungsabwehr, die Duplikatbearbeitung und die Debugging-Hooks von Anfang an hinzu.
Anatomie eines Webhook-HTTP-Anforderung
Bevor man code schreibt, hilft es, die Anfrage als Roh-HTTP anstatt als Framework-Objekt anzusehen. Ein typischer Webhook ist einfach ein HTTP-POST an einen öffentlichen Endpunkt mit Kopfzeilen und einem JSON-Körper.
Ein einfacher Rohanfrage
POST /webhooks/orders HTTP/1.1
Host: your-app.example
Content-Type: application/json
User-Agent: Provider-Webhooks/1.0
X-Webhook-Signature: sha256=abc123example
X-Webhook-Timestamp: 1712345678
{
"event": "order.created",
"id": "evt_123",
"data": {
"order_id": "ord_456",
"status": "created"
}
}Die wichtigen Teile sind klar:
- MethodeIn der Praxis sind Webhook-Lieferungen normalerweise POST-Anfragen.
- Content-TypeDie meisten modernen Anbieter senden JSON.
- User-AgentHilfreich für die Fehlersuche, aber nie genug für Vertrauen.
- Signaturkopfzeile. Übermittelt die Authentifizierungsprüfung des Anbieters.
- Timestamp-Kopfzeile. Wird verwendet, um veraltete oder wiederholt eingereichte Anfragen abzulehnen.
Weshalb die Form der Nachricht wichtig ist
Dein code kümmert sich normalerweise nicht um jeden einzelnen Feld. Es kümmert sich um den Ereignistyp, die Ereignis-ID und das Geschäftselement darin. data. Deshalb analysieren gute Handler nur das, was sie benötigen, und loggen den Rest für die Fehlerbehebung.
OpenAPI modelliert diesen Muster direkt. OpenAPI 3.1.0 fügte erstmals eine erste-Klasse-Unterstützung für Webhooks mit einer obersten Ebene hinzu, auf der jeder Webhook wie ein Pfad-Element beschrieben wird, aber durch den Anbieter ausgelöst wird. Die kanonische Beispiel verwendet einen Webhook mit einer webhooks Operation newPet , einem JSON-Anforderungskörper und einer post Antwort, um die Empfangsbestätigung anzuzeigen, wie im 200 Bild gezeigt wird. OpenAPI-Webhook-Beispiel.
Wenn Sie Ihre eigenen Empfänger- oder Anbieterverträge dokumentieren, helfen starke Beispiele mehr als abstrakte Schema-Texte. Ich bevorzuge Referenzen wie SheetMergy’s API Dokumentationsbeispiele weil sie es offensichtlich machen, wie Anforderungsbeispiele, Feldbeschreibungen und erwartete Antworten zusammenpassen.
Eine Webhook ist einfach auf der Transportebene. Die meisten Fehler kommen von mangelnden Annahmen über Kopfzeilen, Körpercodierung oder Signaturregeln.
Webhook-Signaturen sicher überprüfen
Eine signierte Webhook-antwort beantwortet eine Frage: Ist dieser Payload von jemandem gekommen, der das gemeinsame Geheimnis kennt?
Dies ist anders als die Frage, ob der Anfragezeitpunkt recent ist oder ob Sie ihn bereits bearbeitet haben. Die Signaturüberprüfung ist der erste Zaun, nicht der letzte.
Die Überprüfungssequenz
Die übliche HMAC-Fluss sieht wie folgt aus:
- Lesen Sie die Signatur aus dem Anbieterkopf.
- Lesen Sie den den Rohanforderungskörper genau so wie er erhalten wurde.
- Laden Sie Ihren Webhook-Schlüssel aus der sicheren Konfiguration.
- Rechnen Sie den erwarteten HMAC mit demselben Algorithmus neu.
- Vergleichen Sie die empfangene Signatur und die berechnete Signatur mit einer zeitungssicheren Vergleichsmethode.
- Akzeptieren Sie den Anforderung, wenn sie übereinstimmen.
Dass der Rohkörper-Schritt ist, wo viele sonst gute Implementierungen scheitern. Wenn Ihr Framework den JSON-Code zuerst parsen, die Whitespaces reformieren oder die Kodierungsdetails ändern, bevor Sie das Hashen, dann wird Ihre berechnete Signatur nicht mit der des Providers übereinstimmen.
What to watch for in real code
Diese sind die Fehler, die ich am häufigsten sehe:
- den JSON-parsierten Hash. Machen Sie das nicht
JSON.stringify(req.body)und erwarten Sie, dass es übereinstimmt. - Mit normaler Zeichenfolgengleichheit verwenden.. Verwenden Sie eine zeitungssichere Vergleichsmethode.
- Geheime Daten hartcoden.. Bewahren Sie sie in Umgebungsvariablen oder einem Geheimnisspeicher auf.
- An Kopfzeilen allein vertrauen.. Eine Signaturkopfzeile ist nur dann bedeutungsvoll, wenn Sie sie überprüfen.
Für Teams, die die Geheimnisverwaltung zwischen Diensten verschärfen, ist die Anleitung von Capgo zu den API-Schlüsselsicherheit für die Einhaltung der App-Store-Vorschriften relevant, weil dieselbe Disziplin hier gilt. Die geheime Rotation, der skalierte Zugriff und die Vermeidung von Lecks in den Protokollen zählen auch für Webhook-Empfänger.
Eine allgemeine Verifizierungsbeispiel
const crypto = require('crypto');
function verifySignature(rawBody, receivedSignature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
const a = Buffer.from(receivedSignature, 'utf8');
const b = Buffer.from(expected, 'utf8');
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}Dies ist absichtlich allgemein gehalten. Realisierte Anbieter geben oft die Signatur vor, kombinieren die Zeitstempel in den signierten Inhalt oder kodieren den Digest anders. Die Regel bleibt gleich. Folgen Sie dem genauen Signierungsformat des Anbieters und überprüfen Sie immer gegen den Rohinhalt.
Schutz vor Wiedergabeangriffen
Eine signierte Webhook kann immer noch gefährlich sein, wenn sie Stunden später eintrifft und Ihr Handler sie als neue behandelt. Das passiert häufiger als Teams erwarten. Proxy-Server loggen den Traffic, Anforderungspayloads gelangen in den falschen Ort oder ein Anbieter wiederholt nach einem Netzwerkfehler und Ihr Endpunkt verarbeitet denselben Ereignis zweimal.
Die Signaturverifizierung beantwortet eine Frage: Hat der Absender diesen Payload mit dem gemeinsamen Geheimnis erstellt? Die Wiedergabeprävention beantwortet eine andere: Soll diese Anfrage noch jetzt akzeptiert werden? Produktionsempfänger benötigen beide.
Der Mindestcheck, der tatsächlich zählt
Ein praktischer Wiedergabeabwehr beginnt mit einer signierten Zeitstempel. Der Anbieter enthält einen Zeitstempel in den Kopfzeilen oder im signierten Nachrichten und Ihr Empfänger lehnt Anfragen ab, die außerhalb eines kleinen Toleranzfensters liegen.
Dieser Fluss sollte wie folgt aussehen:
- Lesen Sie den Zeitstempel aus der vom Anbieter definierten PositionVermeiden Sie es, den Kopfzeilennamen zu erraten.
- Analysieren Sie ihn als Ganzzahl oder als RFC-formatierten DatumBasierend auf der Spezifikation des Anbieters.
- Vergleichen Sie ihn mit Ihrem Server-Uhrzeigerschnellgang.
- Anfragen, die zu alt oder zu weit in der Zukunft sind, abweisen.
- Überprüfen Sie den Zeitstempel als Teil des Signaturverfahrens wenn der Anbieter dies unterstützt
Das letzte Punkt ist wichtig. Wenn der Zeitstempel nicht durch die Signatur abgedeckt ist, kann ein Angreifer einen frischen Zeitstempel einsetzen und den ursprünglichen Body wiederholen. Ich überprüfe immer das genaue Signierformat des Anbieters, bevor ich die Zeitstempellogik vertraue
Welche Toleranzzeit wählen
Fünf Minuten ist ein gängiger Standard. Es ist kurz genug, um die Angriffszeit zu verkürzen, aber lang genug, um kleine Uhrfehler und normale Netzwerkverzögerungen zu überstehen
Es gibt ein Gleichgewicht hier. Ein 30-Sekunden- Fenster klingt sicherer, aber es bricht häufiger in realen Systemen, insbesondere wenn Wiederholungen, Warteschlangen oder regionale Latenz involviert sind. Ein 30-Minuten-Fenster ist einfacher zu bedienen, aber es gibt einem Angreifer viel mehr Zeit, wenn ein signierter Anfrage ausgesetzt wird. Beginnen Sie mit wenigen Minuten, synchronisieren Sie Ihre Server mit NTP und verengen Sie nur, wenn das Liefermuster des Anbieters es unterstützt
Replay-Abwehr ist nicht nur ein Zeitstempel-Check
Zeitstempel-Validierung blockiert veraltete Anfragen. Sie stoppt jedoch nicht die doppelte Verarbeitung innerhalb des gültigen Fensters. Wenn das gleiche signierte Ereignis zweimal innerhalb dieses Fensters geliefert wird, muss Ihre Anwendung es erkennen
Verwenden Sie eine zweite Ebene:
- Verfolgen Sie Ereignis-IDs oder Liefer-IDs in einem kurzlebigen Speicher wie Redis
- Behandle Handler als idempotent so wiederholte Lieferungen erzeugen keine doppelten Bestellungen, E-Mails oder Rechnungsaktionen.
- Log abgelehnte veraltete Anfragen mit Gründen, aber nie geheime oder vollständige sensitive Payloads.
- Geben Sie eine schnelle Antwort zurück nach der Validierung und der Auftragsbearbeitung an anderer Stelle.
Teams, die sich bereits mit Ablaufzeiten und Widerrufen beschäftigen, erkennen das Muster. Capgo's Leitfaden zu Token-Widerrufsmustern in Capacitor-Anwendungen umfasst denselben operativen Gedanken. Ein Kredit oder eine Anfrage, die einmal gültig war, sollte nicht für immer vertrauenswürdig bleiben.
Signiert und veraltet ist immer noch gefährlich.
Ein Webhook-Empfänger in Node.js
Node mit Express ist immer noch der schnellste Weg, um einen ernsthaften Empfänger online zu bekommen, aber es gibt einen Haken, der wichtiger ist als jeder andere. Sie benötigen Zugriff auf den Rohkörper, bevor Express ihn in ein Objekt verwandelt.
Ein Express-Beispiel für Produktionsumgebungen
const express = require('express');
const crypto = require('crypto');
const app = express();
const PORT = process.env.PORT || 3000;
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// Capture raw body for signature verification
app.use(
express.json({
verify: (req, res, buf) => {
req.rawBody = buf;
},
})
);
function safeEqual(a, b) {
const aBuf = Buffer.from(a, 'utf8');
const bBuf = Buffer.from(b, 'utf8');
if (aBuf.length !== bBuf.length) return false;
return crypto.timingSafeEqual(aBuf, bBuf);
}
function verifySignature(rawBody, secret, receivedSignature) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return safeEqual(expected, receivedSignature);
}
function isFresh(timestampHeader, toleranceSeconds = 300) {
const timestamp = Number(timestampHeader);
if (!Number.isFinite(timestamp)) return false;
const now = Math.floor(Date.now() / 1000);
return Math.abs(now - timestamp) <= toleranceSeconds;
}
app.post('/webhooks/example', async (req, res) => {
const signature = req.get('x-webhook-signature');
const timestamp = req.get('x-webhook-timestamp');
if (!WEBHOOK_SECRET) {
return res.status(500).send('Webhook secret is not configured');
}
if (!signature || !timestamp) {
return res.status(400).send('Missing required security headers');
}
if (!isFresh(timestamp)) {
return res.status(401).send('Stale webhook');
}
const valid = verifySignature(req.rawBody, WEBHOOK_SECRET, signature);
if (!valid) {
return res.status(401).send('Invalid signature');
}
// Acknowledge quickly
res.status(200).send('OK');
// Process after acknowledgement
try {
const event = req.body;
console.log('Accepted event:', event.event, event.id);
// enqueueJob(event)
} catch (err) {
console.error('Post-ack processing failed:', err);
}
});
app.listen(PORT, () => {
console.log(`Webhook receiver listening on ${PORT}`);
});Warum diese Struktur hält
Einige Entscheidungen hier sind bewusst getroffen:
- Die Rohkörperfassung erfolgt im Middleware. Das bewahrt die ursprünglichen Bytes für die Hashierung.
- Die Zeitstempelüberprüfung erfolgt vor der Geschäftslogik. Es gibt keinen Grund, für veraltete Verkehr arbeiten zu lassen.
- Die Route gibt schnell zurück
200. Langlaufende Arbeit gehört in eine Warteschlange oder einen Hintergrundauftrag.Die Post-Ack-Verarbeitung ist isoliert - Die Route gibt schnell zurück.. Selbst wenn die Abwärtslogik fehlschlägt, bleibt der Empfängerpfad klein.
Geheime Informationen sind der Schwachpunkt in vielen Webhook-Implementierungen. Halten Sie sie nicht in der Quelle, fügen Sie sie nicht in Testfällen ein und geben Sie sie nicht in Protokollen wieder. Wenn Sie ein umfassenderes Verfahren für die Rotation und die CI-Verwaltung benötigen, bietet Capgo's Guide zu der Verwaltung geheimer Informationen in CI/CD-Pipelines eine gute Lösung.
Ein kurzer Leitfaden hilft, wenn Sie die beweglichen Teile in Aktion sehen möchten:
Was ich für ein lebendiges System ändern würde
Für eine echte Anbieterintegration würde ich eine Deduplikation von Ereignis-IDs in der persistenten Speicherung, strukturierte Protokolle mit Anforderungs-IDs und eine Warteschlange hinter dem Bestätigungsverlauf hinzufügen. Ich würde auch einen einzelnen allgemeinen Endpunkt vermeiden, wenn mehrere Anbieter unterschiedliche Signaturformate verwenden. Trennte Handler sind leichter zu verstehen und schwerer zu brechen.
Ein Webhook-Empfänger in Python erstellen
Flask ist ein guter Anbieter für einen sauberen Webhook-Beispiel, weil die Anforderungshandhabung explizit ist und Pythons Standardbibliothek bereits alles bietet, was Sie für HMAC benötigen.
Das Hauptding, das man beachten muss, ist dasselbe wie in Node. Überprüfen Sie gegen die Rohdaten des Anforderungsbytes und nicht gegen das parsierte JSON-Dictionary.
Ein Flask-Beispiel mit Signatur- und Zeitstempelprüfungen
import os
import time
import hmac
import hashlib
from flask import Flask, request, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get("WEBHOOK_SECRET", "")
def is_fresh(timestamp_header, tolerance_seconds=300):
try:
timestamp = int(timestamp_header)
except (TypeError, ValueError):
return False
now = int(time.time())
return abs(now - timestamp) <= tolerance_seconds
def verify_signature(raw_body, secret, received_signature):
expected = hmac.new(
secret.encode("utf-8"),
raw_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, received_signature)
@app.route("/webhooks/example", methods=["POST"])
def webhook():
if not WEBHOOK_SECRET:
return "Webhook secret is not configured", 500
signature = request.headers.get("X-Webhook-Signature")
timestamp = request.headers.get("X-Webhook-Timestamp")
if not signature or not timestamp:
return "Missing required security headers", 400
if not is_fresh(timestamp):
return "Stale webhook", 401
raw_body = request.get_data()
if not verify_signature(raw_body, WEBHOOK_SECRET, signature):
return "Invalid signature", 401
payload = request.get_json(silent=True) or {}
# Acknowledge receipt
response = jsonify({"status": "ok"})
# In production, queue payload here instead of heavy sync work
print("Accepted event:", payload.get("event"), payload.get("id"))
return response, 200
if __name__ == "__main__":
app.run(port=5000, debug=True)Flask-spezifische Details, die wichtig sind
request.get_data() ist der Schlüsselaufruf hier. Es liefert Ihnen die Rohdaten der Anfragekörper. Wenn Sie direkt zu request.jsonSie haben bereits die Grenze überschritten, an der sich Unterschiede in der Signatur verwirrend machen.
Einige Implementierungsanmerkungen:
- Verwenden Sie
hmac.compare_digestanstatt der einfachen Gleichheit. - Behandeln Sie fehlende Header als Client-Fehler und lehnen Sie ab. Verwenden Sie
- für die JSON-Verarbeitung
silent=Truewenn Sie die Fehlerbehandlung kontrollieren möchten, anstatt dass Flask eine Ausnahme auslöst. Halten Sie die Route dünn - . Wenn der Payload etwas teuer auslöst, sollten Sie die Arbeit in die Warteschlange eintragen.Verwenden Sie
Vermeide es, Debug-Fehlern durch Entspannung von Sicherheitsprüfungen. Debug sie, indem Sie genau die Bytes drucken, die Sie gehasht haben, und genau die Formatierung, die der Anbieter erwartet.
Wo sich die Teams normalerweise verheddern
Die häufige Fehlroute ist das Testen mit einem handgebausenen JSON-Körper, dann das Wechseln zu einem realen Anbieter und das Feststellen, dass die Signatur nicht mehr übereinstimmt. Das bedeutet normalerweise eines von drei Dingen: Der Anbieter signiert einen timestampierten Umschlag, die Signatur ist anders als Sie angenommen haben, oder Middleware hat den Körper vor der Verifizierung geändert.
Wenn das passiert, stoppe es, die Crypto-code zu ändern. Fange die Rohkopfzeilen und den Rohkörper ein, reproduziere den Hash in einem kleinen isolierten Skript und erst dann setze ihn wieder in die Flask-Routen ein.
Ein Webhook-Empfänger in Go bauen
Go ist eine großartige Wahl für Webhook-Empfänger, weil die Standardbibliothek ausreicht. Sie brauchen kein Framework, um einen kleinen, zuverlässigen Handler zu bekommen, und die code ist leicht zu überprüfen.
Etwas zu beachten ist der Körper-Handling. r.Body ist ein Stream. Lies ihn einmal, hash die Bytes, die Sie bekommen haben, und dann unmarshale von denselben Bytes.
Ein Beispiel aus der Standardbibliothek
package main
import (
"crypto/hmac"
"crypto/sha256"
"crypto/subtle"
"encoding/hex"
"encoding/json"
"io"
"log"
"net/http"
"os"
"strconv"
"time"
)
type WebhookPayload struct {
Event string `json:"event"`
ID string `json:"id"`
Data json.RawMessage `json:"data"`
}
func isFresh(timestampHeader string, toleranceSeconds int64) bool {
ts, err := strconv.ParseInt(timestampHeader, 10, 64)
if err != nil {
return false
}
now := time.Now().Unix()
diff := now - ts
if diff < 0 {
diff = -diff
}
return diff <= toleranceSeconds
}
func verifySignature(rawBody []byte, secret string, received string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
if len(expected) != len(received) {
return false
}
return subtle.ConstantTimeCompare([]byte(expected), []byte(received)) == 1
}
func webhookHandler(secret string) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
signature := r.Header.Get("X-Webhook-Signature")
timestamp := r.Header.Get("X-Webhook-Timestamp")
if signature == "" || timestamp == "" {
http.Error(w, "missing required security headers", http.StatusBadRequest)
return
}
if !isFresh(timestamp, 300) {
http.Error(w, "stale webhook", http.StatusUnauthorized)
return
}
rawBody, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "failed to read body", http.StatusBadRequest)
return
}
if !verifySignature(rawBody, secret, signature) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var payload WebhookPayload
if err := json.Unmarshal(rawBody, &payload); err != nil {
http.Error(w, "invalid json", http.StatusBadRequest)
return
}
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
log.Printf("accepted event=%s id=%s", payload.Event, payload.ID)
}
}
func main() {
secret := os.Getenv("WEBHOOK_SECRET")
if secret == "" {
log.Fatal("WEBHOOK_SECRET is not set")
}
http.HandleFunc("/webhooks/example", webhookHandler(secret))
log.Println("listening on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}Warum Go hier solid aussieht
Ein paar Vorteile fallen auf:
- Der Handler ist explizit. Keine versteckte Middleware-Magie.
- Typing hilft an den Rändern.. Die Header-Verarbeitung, die Zeitstempelumrechnung und die JSON-Entschlüsselung funktionieren alle klar.
- Die Standardkryptopakete reichen aus.. Keine zusätzliche Abhängigkeit für die grundlegende HMAC-Verifizierung.
Betriebsnotizen
Wenn der Webhook-Verkehr zunimmt, bietet Go's Konkurrenzmodell Ihnen Platz, um Hintergrundarbeit ohne Änderung Ihres HTTP-Eingangs zu verteilen. Selbst dann sollten Sie den Empfänger eng halten. Akzeptieren, validieren, bestätigen und dann weitergeben.
Die stärksten Go-Webhook-Handler, die ich gesehen habe, bleiben langweilig. Sie vermischen nicht die Transportverifizierung mit der Geschäftslogik und sie tun keine Datenbank-schweren Arbeit vor der Antwort zurück.
Wichtige Debugging-Techniken
Ein Webhook-Fehler zeigt sich normalerweise als Support-Nachricht und nicht als Stack-Trace. Der Anbieter sagt, sie hätten das Ereignis geliefert. Ihr Endpunkt sagt, nichts habe das Anwendungsprogramm erreicht, oder die Signaturverifizierung sei auf einer Anfrage gescheitert, die auf den ersten Blick wie eine gültige aussieht. An diesem Punkt ist Debugging daran gelegen, die genaue HTTP-Austausch, Byte für Byte, wiederherzustellen und zu beweisen, wo es gebrochen ist.
Ein praktisches Debugging-Toolkit
Beginnen Sie mit der Drahtformatvorlage.
Wenn eine Signaturprüfung fehlschlägt, fangen Sie den Rohanforderungskörper genau so auf, wie er erhalten wurde, zusammen mit den zur Verifizierung verwendeten Header. In der Praxis ist der Fehler oft langweilig. Ein Framework hat JSON vor der Hashierung geparst, ein Proxy hat die Kodierung geändert oder ein Testwiedergabe hat den ursprünglichen Timestamp-Header übersehen. Die Protokollierung des geparsten Objekts reicht nicht aus. Sie benötigen die ursprünglichen Bytes und die Verifizierungsinputs.
Diese Werkzeuge helfen, das Problem schnell zu isolieren:
- RohanforderungsaufzeichnungLoggen Sie Header, Inhaltstyp, Inhaltslänge und den unveränderten Körper während der Ermittlung.
- AnforderungsinspektionsendpunkteDienste wie
webhook.sitebestätigen, was der Absender übermittelt hat. - Lokale Tunnelung.
ngrokund ähnliche Werkzeuge ermöglichen Ihnen, gegen einen lokalen Empfänger zu testen, während der Anbieter im Bilde ist. - Manuelle WiedergabeRekonstruieren Sie die Anforderung mit
curloder Postman mit demselben Body und Header. Das ist die schnellste Möglichkeit, zu überprüfen, ob Ihr code oder der Anbieter-Payload das Problem ist. - Anbieterlieferantenprotokolle. Das Absender-Dashboard enthält oft Antwortcodes, Wiederholungsverlauf und Anforderungsidentifikatoren, die Sie gegen Ihre Protokolle abgleichen können.
Die Muster sind wichtig. Arbeiten Sie von außen nach innen. Überprüfen Sie zunächst, ob der Anbieter das erwartete gesendet hat. Dann überprüfen Sie, ob Ihr Server die gleichen Bytes erhalten hat. Dann überprüfen Sie, ob Ihr code die gleichen Bytes mit den gleichen Geheimnis- und Zeitstempelregeln gehasht hat.
Protokollierung, die wirklich hilft
Ein gutes Webhook-Protokoll sollte drei Fragen in einer Suche beantworten:
| Fragen | Nützliche Protokollfelder |
|---|---|
| Kam die Anfrage an? | route, method, received_at |
| Warum wurde sie abgelehnt? | missing_header, stale_timestamp, signature_failed |
| Kann ich es später korrelieren? | event_id, provider_request_id |
Ein vierter Feld hilft in realen Systemen. Fügen Sie einen lokalen request_id erstellt von Ihrem Empfänger, damit Sie den Anforderungsverlauf durch Ihre App, Warteschlange und Arbeiter-Protokolle verfolgen können.
Seien Sie wählerisch, was Sie speichern. Loggen Sie niemals Geheimnisse. Vermeiden Sie es, vollständige Produktionslasten zu dumpen, wenn sie Kunden-Daten, Zugriffstoken oder Rechnungsdaten enthalten. Ein sichereres Muster ist, Metadaten plus einen kurzen Body-Hash zu loggen. Das lässt Ihnen noch immer Wiederholungen vergleichen und überprüfen, ob zwei Lieferungen identisch waren.
Reproduzieren Sie Fehlfälle mit den ursprünglichen Eingaben
Das ist der Teil, den grundlegende Tutorials auslassen. Wenn Sie den fehlgeschlagenen Anforderungsaufruf nicht genau wiederholen können, raten Sie.
Speichern Sie einen fehlgeschlagenen Webhook als:
- rohe Bytes des Körpers
- alle signaturbezogenen Header
- Anforderungszeitstempel
- Inhalts-Typ
- Anbieteranforderungs-ID
Dann wiederholen Sie es gegen einen Testendpunkt. Wenn die Wiederholung erfolgreich ist, vergleichen Sie, was sich im Transit geändert hat. Häufige Verursacher sind Middleware, die die Anforderungskörper normalisiert, Encoding-Missverständnisse und Last-Entscheider, die Kopfzeilen streichen oder umschreiben. Ich habe auch Fälle gesehen, in denen Teams Payloads aus pretty-printed Dashboard-Ansichten kopierten, anstatt den tatsächlichen Anforderungskörper. Der Unterschied im Whitespace allein reichte aus, um die HMAC-Verifizierung zu brechen.
Für eine breitere Veröffentlichung und mobile Transport-Überprüfung zeigt sich das gleiche Debugging-Diskussionsstil in der Anleitung von Capgo zu Tools für die Überprüfung von OTA-Updates in Capacitor. Ein anderer Transport, dieselbe Lektion. Fassen Sie den tatsächlichen Anforderungspfad vor dem Ändern der Anwendung code.
Wenn die Signaturverifizierung fehlschlägt, inspizieren Sie die Rohbytes, die genauen Kopfzeilen, die bei der Verifizierung verwendet wurden, und den Timestamp-Wert, bevor Sie die Kryptographie code berühren.
Ein Checkliste für Produktionsreife Webhooks
Ein Webhook-Handler sieht in der Regel in der Staging-Umgebung gut aus, bis zum ersten Wiederholungssturm, dem fehlerhaften Payload oder dem Signaturmismatch um 2 Uhr morgens. Die Produktionsbar ist höher. Der Empfänger muss gefälschte Anforderungen ablehnen, legitime Wiederholungen akzeptieren und Operatoren genug Signal geben, um Fehlern nachzugehen, ohne sensible Daten preiszugeben.
Sicherheits- und Korrektheitsprüfungen
- Verifizieren Sie jeden Anforderungssignatur. URL-Endpunkte werden preisgegeben. Test-URLs werden in Chat geteilt. Die Signaturverifizierung ist der Kontrolle, die Ihnen sagt, dass der Sender den geteilten Geheimcode kannte.
- Alte Anforderungen ablehnen. Ein gültiges Signatur auf einem alten Payload kann immer noch wiederholt werden. Stellen Sie eine Toleranz für den Zeitstempel ein, die der Anbieter-Retry-Modell entspricht.
- Hashen Sie den Rohkörper, nicht den parsierten JSON.. Middleware kann Schlüssel neu anordnen, Leerzeichen normalisieren oder die Kodierung ändern. Die Verifizierung muss gegen die genauen Bytes durchgeführt werden, die eingegangen sind.
- Halten Sie Signaturschlüssel aus code heraus.. Umgebungsvariablen sind ein Grundlevel. Ein Secrets-Manager ist ein besserer Ansatz, wenn Sie regelmäßig Anmeldeinformationen rotieren oder auf mehreren Umgebungen laufen.
- Fehler schließen bei Auth-Fehlern.. Wenn der Signaturheader fehlt, fehlerhaft ist oder einen unerwarteten Scheme verwendet, lehnen Sie den Antrag ab und loggen Sie die Gründe.
Zuverlässigkeitsprüfungen.
- Bestätigen Sie schnell.. Anbieter behandeln normalerweise jede 2xx als Erfolg, also überprüfen Sie den Antrag, speichern Sie, was Sie benötigen, und bewegen Sie langsame Arbeit in eine Warteschlange oder einen Arbeiter.
- Machen Sie Handler idempotent.. Das gleiche Ereignis kann mehr als einmal eintreffen. Verschieben Sie Seiteneffekte auf ein Ereignis-ID, eine Liefer-ID oder einen anderen stabilen Anbieter-Bezeichner.
- Prädiktive Fehlercodes zurückgeben. Verwenden Sie
400für fehlerhaftes Eingabedaten,401oder403Kontext: HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `alternatives_cta_questions`). Seite/Bereich: Vergleichsseite für lebendige Updates von Capacitor. Rolle: Langer Marketing- oder Rechtsparagraph. Gesehen in: Seite alternatives.astro. Bewahren Sie Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau auf. Nachrichtenschlüssel `alternatives_cta_questions` (Alternativen-CTA-Fragen). | HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `appflow_cta_questions`). Seite/Bereich: Appflow-Vergleichs- und -Migration-Marketing-Kopie. Rolle: Langer Marketing- oder Rechtsparagraph. Gesehen in: Seite ionic-appflow.astro. Bewahren Sie Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau auf. Nachrichtenschlüssel `appflow_cta_questions` (Appflow-CTA-Fragen). | HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `capwesome_cta_questions`). Seite/Bereich: Capawesome-Vergleichsseite. Rolle: Langer Marketing- oder Rechtsparagraph. Gesehen in: Seite capwesome.astro. Bewahren Sie Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau auf. Nachrichtenschlüssel `capwesome_cta_questions` (Capwesome-CTA-Fragen). | Seite/Bereich: Beratungsdienste-Seite. Rolle: Abschnittstitel oder Slogan. Gesehen in: Seite consulting.astro. Bewahren Sie Capgo-Produkt- und -Markenbegriffe sowie Entwicklertitel genau auf. Nachrichtenschlüssel `consulting_faq_subtitle` (Beratungsdienste-Fragebogen-Untertitel). | Seite/Bereich: Appflow-Vergleichs- und -Migration-Marketing-Kopie. Rolle: Kurzer UI-Label oder Navigationselement. Gesehen in: Seite ionic-appflow.astro, Seite ionic-enterprise-plugins.astro, Seite Lösungen/ionic-enterprise-plugins.astro. Nachrichtenschlüssel `appflow_plugins_or` (Appflow-Plugins-oder).5xxfür fehlgeschlagene Verifizierung und - nur dann, wenn Ihr System das Problem ist. Dies erleichtert das Verhalten von Provider-Wiederholungen, das leichter zu verstehen ist.Setzen Sie Grenzen vor der Analyse
- . Setzen Sie die Anforderungsgröße, den Inhaltstyp und die Anzahl der Header frühzeitig. Dies verhindert, dass ein Webhook-Endpunkt in einen allgemeinen Ingrationsloch wird.. Accept only the fields and event types you support. Loose parsing feels convenient at first and becomes expensive during provider API changes.
. Akzeptieren Sie nur die Felder und Ereignistypen, die Sie unterstützen. Loose Parsing fühlt sich zunächst bequem an und wird während von Provider-__CAPGO_KEEP_0__-Änderungen teuer.
Beobachtbarkeitsprüfungen durchführen
Verwenden Sie das Standard:
- Verfolgen Sie die Empfangsbestätigung, die Verifizierung und die Bearbeitung als separate Ergebnisse.
- Loggen Sie die Anforderungs-IDs, die Ereignis-IDs, den Signaturstatus und den Zeitstempel-Schiebebetrag.
- Messungen der Warteschlangenverzögerung, der Handlerlatenz und der Wiederholungsrate.
- Halten Sie einen sicheren Wiedergabe-Weg für die Staging- oder Wiederholungsarbeitsabläufe bereit.
- Warnen Sie auf Änderungen von Mustern, wie z.B. ein Anstieg der Signaturfehler oder Duplikate
Capgo ist ein nützliches Beispiel für den breiteren Betriebspunkt. Es umfasst Werkzeuge rund um die Lieferung von Updates und die Beobachtbarkeit in seinem Update-Workflow, und Teile seines Ökosystems berühren auch webhook-bezogene Flüsse. Die Lektion ist praktisch. Lieferungssysteme benötigen Sichtbarkeit von der Empfangsbestätigung bis zur Beendigung.
Wenn ein Team die oben genannten Überprüfungen abdeckt, ist der Webhook-Receiver in der Regel in guter Verfassung für die Produktion. Wenn ein Item fehlt, zeigt sich dieser Riss normalerweise während eines Vorfalls und nicht während der Demo.
Häufig gestellte Fragen zu Webhooks
Welchen Status code sollte ich zurückgeben?
Rufen Sie eine 2xx Wenn Sie den Webhook akzeptiert haben. Wenn die Validierung fehlschlägt, geben Sie einen Client- oder Auth-Fehler zurück, der der Fehlschlag entspricht, wie z.B. 400 Für fehlerhaftes Eingabedaten oder 401 Für ungültige Authentifizierungsdaten. Halten Sie diese Logik konsistent, damit die Anbieter-Dashboards einfacher zu interpretieren sind.
Soll ich den Webhook synchron verarbeiten?
Normalerweise nicht. Validieren Sie ihn, bestätigen Sie ihn, und schieben Sie dann die tatsächliche Arbeit in eine Warteschlange oder einen Hintergrundarbeiter. Das hält die Lieferungspfad schnell und reduziert duplicate Wiederholungsversuche, die durch langsames Downstream-Verarbeitung verursacht werden.
Wie soll ich mit Wiederholungen umgehen?
Ziehen Sie sie vor. Bauen Sie Idempotenz in Ihren Handler ein, damit das Empfangen des gleichen Ereignisses nicht zu doppelten Nebeneffekten führt. Ereignis-IDs oder Anbieter-Lieferungs-IDs sind die üblichen Anker dafür.
Was passiert, wenn Ereignisse außerhalb der Reihenfolge eintreffen?
Entwerfen Sie Handler, die bei Bedarf tolerant gegenüber der Reihenfolge sind. Wenn das Geschäftsprozess eine Sequenz erfordert, persistieren Sie genug Zustand, um veraltete Übergänge zu erkennen, anstatt anzunehmen, dass die Lieferungspfad die Ereignisreihenfolge widerspiegelt.
Wie gehe ich mit Änderungen der Webhook-Version um?
Versionieren Sie Ihre Handler-Logik absichtlich. Halten Sie die Anbieter-spezifische Parsen isoliert, vermeiden Sie, dass Sie Payload-Voraussetzungen durch Ihr Codebase streuen, und fügen Sie Tests mit realen gespeicherten Beispielen hinzu, bevor Sie die Unterstützung für eine neue Format rollen.
Wenn Ihr Team Capacitor oder Electron-Apps bereitstellt, Capgo Es lohnt sich, darüber zu erfahren, weil es Teams eine kontrollierte Möglichkeit bietet, signierte Web-Updates bereitzustellen, das Rollout-Verhalten zu beobachten und von Unfällen ohne Wartezeit auf die App-Store-Überprüfung zu reagieren, was dem gleichen Ingenieursinstinkt entspricht, hinter dem eine solide Webhook-Design steht: Eingaben validieren, Freisetzungswege beobachten und Wiederherstellung beschleunigen.
