Webhooks

Webhooks ermöglichen es Ihrem System, in Echtzeit über Ereignisse in Ihrem Shop informiert zu werden. Wenn ein Ereignis eintritt (z.B. neue Bestellung, Zahlung eingegangen), sendet das System eine HTTP-POST-Anfrage an Ihre konfigurierte URL.

Ereignistypen

Ereignis	Beschreibung
`order.created`	Neue Bestellung eingegangen
`order.paid`	Zahlung für Bestellung bestätigt
`order.shipped`	Bestellung wurde versandt
`order.cancelled`	Bestellung wurde storniert
`order.refunded`	Rückerstattung wurde veranlasst
`payment.completed`	Zahlung erfolgreich abgeschlossen
`payment.failed`	Zahlung fehlgeschlagen
`product.created`	Neues Produkt erstellt
`product.updated`	Produkt aktualisiert
`product.deleted`	Produkt gelöscht
`customer.registered`	Neuer Kunde registriert

Webhook-Payload

Jede Webhook-Anfrage enthält folgende Header:

POST https://ihre-url.example.com/webhook
Content-Type: application/json
X-Webhook-Event: order.paid
X-Webhook-Timestamp: 1705312200

Beispiel-Payload für order.paid:

{
  "event": "order.paid",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "orderId": 1001,
    "orderNumber": 10042,
    "customerEmail": "[email protected]",
    "totalAmount": 2490.00,
    "currency": "EUR",
    "paymentMethod": "paypal"
  }
}

Webhook-Verwaltung via API

Webhooks auflisten

GET /api2/admin/webhooks?status=failed&eventType=order.paid&page=1&limit=20

Gibt eine paginierte Liste aller Webhook-Einträge zurück, inklusive Statistiken nach Status.

Query-Parameter:

Parameter	Typ	Beschreibung
`status`	string	Filter: `pending`, `delivered`, `failed`
`eventType`	string	Filter nach Ereignistyp
`page`	number	Seite (Standard: 1)
`limit`	number	Einträge pro Seite (Standard: 20)

Antwort:

{
  "webhooks": [
    {
      "id": 501,
      "eventType": "order.paid",
      "url": "https://ihre-url.example.com/webhook",
      "status": "delivered",
      "attempts": 1,
      "createdAt": 1705312200,
      "deliveredAt": 1705312205
    }
  ],
  "total": 38,
  "stats": {
    "pending": 2,
    "delivered": 35,
    "failed": 1
  }
}

Webhook-Details abrufen

GET /api2/admin/webhooks/{id}

Gibt einen einzelnen Webhook-Eintrag mit vollständigem Payload und Fehlermeldungen zurück.

Webhook manuell in die Warteschlange stellen

POST /api2/admin/webhooks
Content-Type: application/json

{
  "eventType": "order.paid",
  "payload": {
    "orderId": 1001,
    "orderNumber": 10042
  },
  "url": "https://ihre-url.example.com/webhook"
}

Wird für Tests und Debugging verwendet. Die URL wird auf SSRF-Angriffe geprüft. Falls keine URL angegeben wird, wird die Standard-Webhook-URL aus der Konfiguration verwendet.

Antwort (201):

{
  "id": 502,
  "status": "pending",
  "eventType": "order.paid",
  "createdAt": 1705315800
}

Fehlgeschlagenen Webhook erneut senden

POST /api2/admin/webhooks/{id}/replay

Setzt den Status des Webhooks auf pending und löscht bisherige Fehlerinformationen, damit der Hintergrundprozess ihn beim nächsten Zyklus erneut versendet.

Hinweis: Die erneute Zustellung erfolgt nicht sofort, sondern beim nächsten Durchlauf des Webhook-Prozessors.

Antwort (200):

{
  "id": 501,
  "status": "pending",
  "attempts": 0
}

Webhook löschen

DELETE /api2/admin/webhooks/{id}

Entfernt den Webhook-Eintrag aus der Warteschlange.

Antwort (200):

{ "success": true }

Wiederholungsverhalten

Bei fehlgeschlagener Zustellung (Timeout, HTTP-Fehler 4xx/5xx) versucht das System den Webhook automatisch erneut zu senden:

Versuch	Wartezeit
1. Wiederholung	5 Minuten
2. Wiederholung	30 Minuten
3. Wiederholung	2 Stunden
4. Wiederholung	12 Stunden

Nach 4 fehlgeschlagenen Versuchen wird der Webhook als failed markiert und nicht mehr automatisch gesendet. Verwenden Sie den Replay-Endpunkt, um ihn manuell erneut zu senden.

Empfehlungen für Ihre Webhook-Endpoint

Antworten Sie schnell: Geben Sie innerhalb von 5 Sekunden 200 OK zurück. Aufwendige Verarbeitung in einen Hintergrund-Job auslagern.
Idempotenz: Derselbe Webhook kann mehrfach ankommen. Verwenden Sie die Webhook-ID zur Deduplizierung.
Zeitstempel prüfen: Validieren Sie X-Webhook-Timestamp, um sehr alte Nachrichten abzuweisen.
HTTPS verwenden: Webhook-URLs werden auf gültige HTTPS-Endpunkte geprüft.

Webhook-URL konfigurieren

Die Standard-Webhook-URL wird in den Shop-Einstellungen unter Einstellungen → API & Webhooks konfiguriert oder per Umgebungsvariable MRP_WEBHOOK_URL gesetzt.