Webhook-Integrationen: Automatisiere deine Goodie Bags

# Webhook-Integrationen: Automatisiere deine Goodie Bags

Webhooks ermöglichen die Automatisierung und Integration mit externen Systemen. Mit Vigoba kannst du sowohl Daten empfangen (Incoming) als auch Benachrichtigungen versenden (Outgoing).

—

## Was sind Webhooks?

Webhooks sind automatische HTTP-Benachrichtigungen zwischen Systemen. Stell dir vor:

– Jemand kauft ein Ticket bei Eventbrite → Vigoba fügt automatisch den Empfänger hinzu
– Ein Teilnehmer öffnet den Goodie Bag → Dein CRM wird benachrichtigt

**Keine manuellen Importe, keine manuellen Exports – alles automatisch!**

—

## Incoming Webhooks (IPN)

Empfange Daten von externen Systemen wie Ticketing-Plattformen.

### Unterstützte Plattformen

### So richtest du es ein

1. **Webhook-URL erstellen**
– Öffne deinen Goodie Bag
– Gehe zu „Webhooks“ → „Incoming“
– Klicke auf „Webhook erstellen“
– Kopiere die generierte URL

2. **URL in externer Plattform eintragen**
– Bei Eventbrite: Webhook-Settings
– Bei Stripe: Developer Dashboard → Webhooks
– Bei PayPal: IPN-Einstellungen

3. **Feld-Mapping konfigurieren** (bei benutzerdefinierten Webhooks)
– E-Mail-Feld: z.B. `email`, `customer.email`, `data.attendee.email`
– Name-Feld (optional): z.B. `name`, `customer.name`

4. **Aktion wählen**
– Empfänger hinzufügen
– Magic Link automatisch senden ✉️

### Praxisbeispiel: Eventbrite

**Szenario:** Jeder Ticketkäufer soll automatisch den Goodie Bag erhalten.

1. Erstelle Incoming Webhook in Vigoba → URL kopieren
2. In Eventbrite: Organisation → Webhooks → „Add Webhook“
3. URL einfügen, Event auswählen
4. Trigger: „order.placed“
5. Aktiviere „Magic Link automatisch senden“

**Ergebnis:** Käufer erhält Ticket-Bestätigung von Eventbrite UND Magic Link zum Goodie Bag von Vigoba – vollautomatisch!

### Sicherheitseinstellungen

– **IP-Whitelist:** Nur bestimmte IPs erlauben (empfohlen für Produktivsysteme)
– **Signatur-Verifizierung:** HMAC-SHA256, Stripe-Signaturen, PayPal-IPN
– **Produkt-ID Filter:** Nur bestimmte Produkte/Tickets verarbeiten

### Webhook-Log

Alle eingehenden Webhooks werden protokolliert:
– Zeitstempel
– Quell-IP
– Payload (gekürzt)
– Verarbeitungsstatus (✅ Erfolgreich / ❌ Fehler)
– Fehler-Details bei Problemen

—

## Outgoing Webhooks

Sende Benachrichtigungen an deine Systeme, wenn in Vigoba etwas passiert.

### Verfügbare Events

### Webhook-Payload

Beispiel für `goody.clicked`:

„`json
{
„event“: „goody.clicked“,
„timestamp“: „2026-01-15T14:30:00Z“,
„data“: {
„bag_id“: 123,
„bag_name“: „Tech Conference 2026“,
„goody_id“: 456,
„goody_title“: „20% Rabatt bei Partner XY“,
„interaction_type“: „click“,
„recipient“: {
„email“: „max@example.com“,
„name“: „Max Mustermann“
},
„metadata“: {
„ip“: „192.168.1.1“,
„user_agent“: „Mozilla/5.0…“,
„device_type“: „mobile“
}
}
}
„`

### Einrichtung

1. Gehe zu „Webhooks“ → „Outgoing“
2. Klicke auf „Webhook hinzufügen“
3. **Ziel-URL:** HTTPS-Endpunkt (z.B. `https://your-app.com/webhooks/vigoba`)
4. **Events:** Wähle die gewünschten Events
5. **Secret:** Generiere ein Geheimnis für Signatur-Verifizierung
6. Speichern & Testen

### Signatur-Verifizierung

Jeder Webhook enthält einen `X-Vigoba-Signature` Header:

„`
X-Vigoba-Signature: sha256=abc123…
„`

**PHP-Beispiel:**
„`php
$payload = file_get_contents(‚php://input‘);
$signature = $_SERVER[‚HTTP_X_VIGOBA_SIGNATURE‘];
$expected = ’sha256=‘ . hash_hmac(’sha256′, $payload, $secret);

if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit(‚Invalid signature‘);
}
„`

**Node.js-Beispiel:**
„`javascript
const crypto = require(‚crypto‘);

function verifySignature(payload, signature, secret) {
const expected = ’sha256=‘ +
crypto.createHmac(’sha256′, secret)
.update(payload)
.digest(‚hex‘);
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
„`

### Retry-Logik

– **3 Versuche** bei Fehlern (5xx, Timeout)
– **Exponentieller Backoff:** 1 Min, 5 Min, 15 Min
– **Webhook-Log** zeigt alle Versuche

—

## Praxisbeispiele

### 1. CRM-Sync (HubSpot, Salesforce)

Bei jedem `recipient.first_access`:
– Lead in CRM anlegen/aktualisieren
– Lead-Score erhöhen
– Sales-Team benachrichtigen

### 2. Slack-Benachrichtigungen

Bei `goody.clicked` mit hohem Wert:
– Message in #sales-leads Channel
– „🎯 Max Mustermann hat den 20%-Gutschein kopiert!“

### 3. Analytics-Integration

Alle Events an eigenes Data Warehouse:
– Langzeit-Analysen
– Custom Dashboards
– A/B-Test-Auswertungen

—

## Best Practices

✅ **HTTPS verwenden** – Webhooks nur an sichere Endpunkte

✅ **Signaturen verifizieren** – Verhindert gefälschte Requests

✅ **Idempotent implementieren** – Gleiche Daten 2x empfangen = gleiches Ergebnis

✅ **Schnell antworten** – 200 OK innerhalb 5 Sekunden, Verarbeitung asynchron

✅ **Log überwachen** – Fehler schnell erkennen und beheben

—

## Fehlerbehebung

### „Webhook nicht empfangen“
– IP-Whitelist geprüft?
– URL korrekt kopiert?
– HTTPS (nicht HTTP)?

### „Signatur ungültig“
– Secret identisch in beiden Systemen?
– Keine zusätzlichen Leerzeichen?

### „Timeout“
– Endpunkt antwortet zu langsam (>5s)
– Verarbeitung in Background-Job verschieben

—

📚 **Weiterführend:** [API-Dokumentation](/docs/api-dokumentation) | [MCP-Integration](/docs/mcp-integration)

Share This Article :