Webhooks

Ein Webhook ist das Gegenteil einer API-Abfrage. Statt dass dein Workflow regelmäßig ein Drittsystem fragt "Gibt es etwas Neues?" — meldet sich das Drittsystem von selbst bei dir, sobald etwas passiert. In 42°OS empfängst du Webhooks über den Webhook Agent.

Push statt Pull

Der Unterschied lässt sich an einem Beispiel festmachen:

Pull (klassische API-Abfrage):

Alle 5 Minuten: "Shop, gibt es neue Bestellungen?"
→ "Nein." → "Nein." → "Ja, eine Bestellung." → verarbeiten

Push (Webhook):

Shop meldet sich: "Neue Bestellung eingegangen!" → sofort verarbeiten

Webhooks sind effizienter, schneller und verursachen weniger Last — sowohl auf deiner Seite als auch beim Drittsystem. Die meisten modernen SaaS-Systeme (Shopify, Stripe, GitHub, Slack, ...) bieten Webhooks an.

Wie ein Webhook funktioniert

Du richtest in 42°OS einen Webhook Agent ein
Der Agent stellt eine URL bereit — das ist dein Empfangsendpunkt
Du trägst diese URL im Drittsystem ein ("Webhook-URL" o. ä.)
Sobald im Drittsystem ein Ereignis eintritt, sendet es einen HTTP POST an deine URL
Der Webhook Agent empfängt die Anfrage und gibt sie als Nachricht in den Workflow

Der Webhook Agent in 42°OS

Der Webhook Agent erzeugt eine eindeutige URL, die du im Drittsystem registrierst. Eingehende Requests landen direkt als Nachricht im Workflow — der Body des Requests wird automatisch geparst und als JSON-Objekt bereitgestellt.

Die URL hat typischerweise folgendes Format:

https://deine-42os-instanz.de/webhooks/empfangen/{agent-token}

Webhook-Payload verarbeiten

Das Drittsystem schickt die Nutzdaten als JSON im Request-Body. Dieser steht nach dem Webhook Agent direkt in der Nachricht zur Verfügung. Wie genau die Struktur aussieht, ist je nach System unterschiedlich — lies die Webhook-Dokumentation des jeweiligen Dienstes.

Beispiel: eine eingehende Bestellbenachrichtigung von einem Shopsystem:

{
  "event": "order.created",
  "order_id": "ORD-20260310-042",
  "customer": {
    "name": "Max Mustermann",
    "email": "max@mustermann.de"
  },
  "total": 149.90,
  "items": [
    {"sku": "PROD-001", "quantity": 2, "price": 49.95},
    {"sku": "PROD-007", "quantity": 1, "price": 50.00}
  ]
}

Webhook-Sicherheit

Da die Webhook-URL öffentlich erreichbar ist, könnte theoretisch jeder beliebige Daten an sie senden. Seriöse Drittsysteme sichern ihre Webhooks daher mit einem Signing Secret — einem gemeinsamen Geheimnis, mit dem jede Anfrage signiert wird.

HMAC-Signatur prüfen

Das Drittsystem berechnet aus dem Request-Body und dem Shared Secret einen Hash und schickt ihn im Header mit (z. B. X-Signature oder X-Hub-Signature-256). Dein Workflow muss diesen Hash selbst berechnen und vergleichen:

// Im JavaScript Agent
const crypto = require('crypto');

const secret = '{% credential webhook_secret %}';
const body = JSON.stringify(input.raw_body);
const expected_signature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

const received_signature = input.headers['X-Signature'];

if (received_signature !== expected_signature) {
  throw new Error('Ungültige Webhook-Signatur — Anfrage abgelehnt');
}

Signaturprüfung nicht überspringen

Ohne Signaturprüfung kann jeder beliebige Daten an deinen Webhook schicken und so Geschäftsprozesse auslösen. Bei produktiven Webhooks die Signaturprüfung immer als ersten Schritt einbauen.

Secret Token als Query-Parameter

Manche einfachere Systeme nutzen statt HMAC ein statisches Token in der URL:

https://deine-instanz.de/webhooks/empfangen/{agent-token}?secret=geheimestoken

Der Webhook Agent prüft ob das secret-Parameter übereinstimmt. Weniger sicher als HMAC, aber besser als gar keine Prüfung.

Typische Anwendungsfälle

Neue Bestellung im Shopsystem → Bestelldaten ins ERP übertragen, Bestätigungs-E-Mail versenden

Zahlung eingegangen (Stripe, PayPal) → Auftragsstatus aktualisieren, Rechnung versenden

Neues Support-Ticket (Zendesk, Jira) → intern weiterleiten, SLA-Timer starten

Code-Push in Git-Repository → Deployment-Workflow auslösen, Benachrichtigung an Team

Formular-Einreichung (Typeform, Tally) → Daten in CRM übernehmen, Folgeaufgabe anlegen

Webhook vs. Schedule vs. API-Abfrage

Methode	Wann geeignet
Webhook	Drittsystem unterstützt Webhooks und kann die URL aufrufen — bevorzugte Variante
Zeitgesteuert (Schedule)	Drittsystem bietet keine Webhooks, aber eine API — Polling als Kompromiss
Manuelle Auslösung	Für einmalige oder bedarfsgesteuerte Prozesse

Wenn ein Drittsystem Webhooks unterstützt, sind sie der Schedule-basierten Abfrage fast immer vorzuziehen: sie reagieren sofort, belasten die API des Drittsystems nicht durch wiederholte Abfragen und sind einfacher zu debuggen da jeder Aufruf ein konkretes Ereignis repräsentiert.

Push statt Pull​

Wie ein Webhook funktioniert​

Der Webhook Agent in 42°OS​

Webhook-Payload verarbeiten​

Webhook-Sicherheit​

HMAC-Signatur prüfen​

Secret Token als Query-Parameter​

Typische Anwendungsfälle​

Webhook vs. Schedule vs. API-Abfrage​