n8n–Adyen Integration automatisieren: Webhooks, Auth & die Grenzen der Payment-Automation

1) Zielbild: n8n Workflows für Adyen Payment Processing (ohne falsche Erwartungen)

Mit n8n Workflows kannst du Adyen API-Events (z. B. Authorisation, Capture, Refund) über Webhooks verarbeiten, an interne Systeme weiterleiten und Folgeschritte automatisieren. Die harte Grenze: Du automatisierst Orchestrierung, nicht die Entscheidungslogik von Adyen (Risikoprüfung, Acquirer-Antworten, 3DS-Flows) und nicht die rechtlich/operativ notwendigen Kontrollen (Reconciliation, Chargeback-Handling, Audit Trails).

2) Webhook Handling in n8n: zuverlässig, idempotent, verifizierbar

2.1 Webhook-Endpoint in n8n anlegen

Nutze in n8n den Webhook-Node (POST). Empfehlung: separater Pfad pro Umgebung (z. B. /adyen/webhook/live vs. /adyen/webhook/test), damit Keys/Secrets sauber getrennt bleiben.

2.2 Adyen-Webhook Payload verstehen (NotificationItems) & Best-Practices

Adyen sendet typischerweise ein Objekt mit notificationItems. Für Automation sind zwei Punkte kritisch:

• Idempotenz: Webhooks können wiederholt kommen. Baue einen dedizierten Idempotency-Key (z. B. Kombination aus pspReference + eventCode + success) und speichere ihn (DB/Redis/Sheet/ERP) bevor du Aktionen auslöst.
• Verifikation: Verifiziere die Signatur (HMAC) bevor du den Event verarbeitest. Sonst ist dein Workflow anfällig für Spoofing.

2.3 Webhook-Flow in n8n (Minimal-Blueprint)

1. Webhook (Trigger) empfängt Adyen Notification.
2. Function / Code: Extrahiere einzelne Items, bilde Idempotency-Key, verifiziere HMAC.
3. IF: Nur verifizierte & noch nicht gesehene Events passieren.
4. HTTP Request oder Custom Node.js Callout: Folgeaktion (Capture, Refund, CRM Update).
5. Respond: Schnell antworten (200), um Retries zu vermeiden.

3) API Authentication: Adyen API-Key, Basic Auth & HMAC (Realität in Automationen)

3.1 Adyen API Authentication (aus Sicht n8n)

Für direkte Calls an die Adyen API wird typischerweise ein API-Key genutzt. In n8n speicherst du ihn in Credentials/Environment-Variablen und setzt ihn im Header. Achte auf:

• Least Privilege: separate API-Keys pro Use-Case (z. B. nur Payment Operations).
• Environment Split: Test/Live strikt trennen (auch die Endpoints).
• Rotation: Keys regelmäßig rotieren und Deploy-Prozess darauf auslegen.

3.2 Webhook Authentication (HMAC Signatur)

Webhook Handling ist nicht „nur ein POST empfangen“. Du solltest HMAC prüfen, um sicherzustellen, dass der Event von Adyen kommt. Das ist besonders wichtig, wenn dein Webhook öffentlich erreichbar ist. In vielen Setups prüfst du pro NotificationItem anhand der von Adyen gelieferten Signatur und deinem HMAC-Secret.

4) Konkrete Umsetzung: JSON Webhook-Konfig & Node.js API Call

Example: JSON Config for Webhooks (n8n Workflow-Export, minimaler Webhook Trigger) ```json { "name": "Adyen Webhook Intake", "nodes": [ { "parameters": { "httpMethod": "POST", "path": "adyen/webhook/live", "responseMode": "onReceived", "options": { "responseCode": 200 } }, "name": "Adyen Webhook", "type": "n8n-nodes-base.webhook", "typeVersion": 2, "position": [300, 200] } ], "connections": {}, "active": false, "settings": { "executionTimeout": 120 } } ``` Example: Node.js Script for API Call (Adyen API-Key Auth + Idempotency) ```javascript /** * Node.js callout used inside n8n (Code node) or as an external microservice. * Demonstrates API Authentication (X-API-Key) and an idempotency key header. */ const ADYEN_API_KEY = process.env.ADYEN_API_KEY; const ADYEN_MERCHANT_ACCOUNT = process.env.ADYEN_MERCHANT_ACCOUNT; // Choose the correct endpoint for your product and environment. // Example shown for Checkout API (payments/details is just illustrative; use the actual endpoint you need). const ADYEN_BASE_URL = process.env.ADYEN_BASE_URL || "https://checkout-live.adyen.com"; async function callAdyen(path, payload, idempotencyKey) { if (!ADYEN_API_KEY) throw new Error("Missing ADYEN_API_KEY"); if (!ADYEN_MERCHANT_ACCOUNT) throw new Error("Missing ADYEN_MERCHANT_ACCOUNT"); const url = `${ADYEN_BASE_URL}${path}`; const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": ADYEN_API_KEY, // Idempotency header name depends on the specific Adyen API. // Keep this here to show the pattern; confirm the exact header in Adyen docs for your endpoint. "Idempotency-Key": idempotencyKey || crypto.randomUUID() }, body: JSON.stringify({ merchantAccount: ADYEN_MERCHANT_ACCOUNT, ...payload }) }); const text = await res.text(); let data; try { data = JSON.parse(text); } catch { data = { raw: text }; } if (!res.ok) { throw new Error(`Adyen API error ${res.status}: ${JSON.stringify(data)}`); } return data; } // Example usage: // (Use the correct path for your operation: capture/refund/cancel, etc.) (async () => { const response = await callAdyen( "/v71/payments/details", { details: { /* ... */ } }, "n8n-adyen-evt-pspRef-12345-AUTHORISATION" ); console.log("Adyen response:", response); })(); ```

5) Automation-Limits im Payment Processing (wo n8n hilft – und wo nicht)

6) Referenz-Architektur (Hybrid): Webhooks → n8n → Adyen API / interne Systeme

```mermaid flowchart LR A[Adyen Notification Webhook] -->|POST notificationItems| B[n8n Webhook Node] B --> C{HMAC valid?} C -->|No| D[Reject / Log Security Event] C -->|Yes| E{Idempotent?} E -->|Seen| F[Return 200 (no-op)] E -->|New| G[Enrich + Map Event] G --> H[Business Actions: ERP/CRM/Slack] G --> I[Optional: Adyen API Call Capture/Refund/Cancel] I --> J[Store Result + Metrics] H --> J J --> K[Respond 200 Quickly] ```

7) Praktische Checks für stabile n8n–Adyen Integrationen

• Fast ACK: Antworte schnell mit 200 und verarbeite schwere Schritte async (Queue/Separate workflow), sonst entstehen Webhook-Retries.
• Persistenter Dedupe-Store: Nicht nur in Memory. Sonst doppelte Captures/Refunds möglich.
• Secret Handling: HMAC Secret und API-Key ausschließlich via n8n Credentials/ENV, nie in Klartext in Nodes.
• Replay-fähige Logs: Speichere Raw Payloads (DSGVO beachten) oder zumindest die normalisierte Event-Form.
• Rate Limits: Bei Burst-Events Throttling einbauen (Batching/Wait).

Wenn du über diese Grenzen hinaus eine skalierbare Orchestrierung mit Governance, SLAs und sicheren Deployments willst, ist ein kombiniertes Setup aus n8n + Services/Queues sinnvoll. Mehr dazu auf AI Automation.