Outbound Webhooks

Über

Payload selbst hat keinen Mechanismus, um bei Dokumentänderungen automatisch einen HTTP-POST abzusetzen. Dieses Plugin schließt diese Lücke und hängt `afterChange`- und `afterDelete`-Hooks an die konfigurierten Collections an. Sobald diese Hooks feuern, wird ein Delivery-Job in der Jobs Queue von Payload eingereiht. Dieser Job sendet einen JSON-Payload (event, collection, docId, volles Dokument, previousDoc bei Updates, occurredAt) an jede abonnierte Endpoint-URL. Da die Zustellung über die Jobs Queue läuft, ist sie nicht blockierend und übersteht Prozessneustarts. Das Plugin eignet sich für die Anbindung von Zapier, Make, n8n, einer CRM-Software oder einem beliebigen HTTP-Dienst. Die zu überwachenden Collections und Events (create, update, delete) lassen sich frei definieren. Endpoint-URLs können entweder im `endpoints`-Array fest hinterlegt oder über die Admin-Collection `webhookEndpoints` von Redakteuren verwaltet werden, die das Plugin hinzufügt (abschaltbar über `enableEndpointsCollection`). Die Zuordnung von Endpoints zu Events erfolgt über Subscription-Pattern wie `orders.create`, `orders.*` oder `*.delete`, wobei `*` als Wildcard auf beiden Seiten funktioniert. Eine pro-Collection konfigurierbare `filter`-Funktion kann steuern, welche Änderungen tatsächlich einen Webhook auslösen, etwa nur bei einem Übergang zu `published`. Die Zustellung erfolgt mindestens einmal. Netzwerkfehler, Timeouts und `5xx`-/`408`-/`429`-Antworten lassen den Job fehlschlagen, sodass die Jobs Queue ihn bis zu `maxRetries`-mal wiederholt (Standard 5). Andere `4xx`-Antworten gelten als dauerhaft, werden protokolliert, aber nicht erneut versucht, da die identische Anforderung auf dieselbe Weise fehlschlagen würde. Ein Circuit-Breaker deaktiviert einen Endpoint nach `failureThreshold` aufeinanderfolgenden Fehlern (Standard 5, 0 zum Deaktivieren), damit ein nicht erreichbares Ziel keine weiteren Job-Retries verbraucht. Admin-verwaltete Endpoints persistieren einen Zähler auf ihrem Dokument. Statische Endpoints greifen auf die kürzliche Zustellungshistorie aus der `webhookLogs`-Collection zurück und heilen nach einer Cooldown-Phase über eine Half-Open-Probe. Sowohl der Breaker als auch die Retry-Skip-Logik setzen voraus, dass `enableDeliveryLog` aktiv bleibt (standardmäßig an). Endpoints mit gesetztem `secret` erhalten einen `X-Webhook-Signature`-Header im Format `t=<timestamp>,v1=<hmac-sha256-hex-digest>`, signiert über den rohen Body. Das Plugin exportiert eine `verifyPayloadSignature`-Hilfsfunktion, die die Signatur prüft und Replays, die älter als 5 Minuten sind, über `toleranceSeconds` standardmäßig abweist. Jede Anfrage enthält zusätzlich die Header `X-Webhook-Event` und `X-Webhook-Id`. Die ID entspricht einer `deliveryId`, die über alle Retries hinweg konstant bleibt, sodass Empfänger darauf deduplizieren sollten statt auf `(event, docId)`. Das Plugin benötigt Payload ^3.0.0, Node 18.20.2+ oder 20.9.0+ und wird als TypeScript-ESM-Modul unter MIT-Lizenz ausgeliefert.

Paketinformationen

Paketname

payload-plugin-outbound-webhooks

Neueste Version

0.3.5

Entpackte Größe

58 kB

Lizenz

MIT

Wöchentliche Downloads

10

Zuletzt veröffentlicht

20. Sep. 2026