--- title: "Webhooks: CheckoutOS-Doku | Chargezen" description: "Ereignisbenachrichtigungen von CheckoutOS in Echtzeit. Aus dem Bereich „API-Referenz“ der Doku zu Chargezen CheckoutOS." url: "https://chargezen.com/de/docs/checkoutos/api/webhooks" lang: "de" updated: "2025-01-16" --- Canonical URL: https://chargezen.com/de/docs/checkoutos/api/webhooks # Webhooks Ereignisbenachrichtigungen von CheckoutOS in Echtzeit Zuletzt aktualisiert: 2025-01-16 **Webhooks** benachrichtigen dich in Echtzeit über Ereignisse in CheckoutOS. Statt die API regelmäßig abzufragen, erhält dein Server Daten direkt beim Ereignis. ## Verfügbare Ereignisse #### Webhook-Ereignisse * upsell.accepted – Kunde hat ein Upsell-Angebot angenommen * upsell.declined – Kunde hat ein Upsell-Angebot abgelehnt * bundle.purchased – Bundle wurde gekauft * experiment.concluded – A/B-Test hat Signifikanz erreicht * order.edited – Kunde hat seine Bestellung bearbeitet * order.cancelled – Kunde hat seine Bestellung storniert * subscription.created – Abo-Angebot wurde angenommen ## Webhooks erstellen 1 #### Zu Webhooks wechseln Gehe zu CheckoutOS → Settings → Webhooks. 2 #### Endpunkt hinzufügen Klicke auf „Add Webhook Endpoint“. 3 #### URL eingeben Gib die HTTPS-URL für den Empfang der Ereignisse ein. 4 #### Ereignisse wählen Wähle die zu abonnierenden Ereignisse. 5 #### Speichern Speichere und notiere den Signaturschlüssel. Webhook über die API erstellen ```bash curl -X POST "https://api.chargezen.com/v1/webhooks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourserver.com/webhooks/checkoutos", "events": ["upsell.accepted", "bundle.purchased"], "enabled": true }' # Response { "id": "wh_123", "url": "https://yourserver.com/webhooks/checkoutos", "events": ["upsell.accepted", "bundle.purchased"], "signing_secret": "whsec_abc123...", "enabled": true } ``` ## Webhook-Inhalt ### upsell.accepted Ereignis: Upsell angenommen ```json { "id": "evt_123456", "type": "upsell.accepted", "created_at": "2025-01-16T14:30:00Z", "data": { "upsell_id": "upsell_abc", "upsell_name": "Premium Add-On", "order_id": "order_789", "shopify_order_id": "5678901234", "customer_id": "cust_456", "product": { "id": "prod_xyz", "title": "Premium Widget", "variant_id": "var_123", "price": 29.99 }, "discount": { "type": "percentage", "value": 15, "amount": 4.50 }, "final_price": 25.49 } } ``` ### bundle.purchased Ereignis: Bundle gekauft ```json { "id": "evt_234567", "type": "bundle.purchased", "created_at": "2025-01-16T15:00:00Z", "data": { "bundle_id": "bundle_def", "bundle_name": "Skincare Starter Kit", "bundle_type": "fixed", "order_id": "order_890", "products": [ { "id": "prod_a", "title": "Cleanser", "quantity": 1 }, { "id": "prod_b", "title": "Toner", "quantity": 1 }, { "id": "prod_c", "title": "Moisturizer", "quantity": 1 } ], "original_price": 89.97, "bundle_price": 71.98, "savings": 17.99 } } ``` ### order.edited Ereignis: Bestellung bearbeitet ```json { "id": "evt_345678", "type": "order.edited", "created_at": "2025-01-16T15:30:00Z", "data": { "order_id": "order_901", "shopify_order_id": "6789012345", "edit_type": "add_items", "changes": { "items_added": [ { "product_id": "prod_new", "quantity": 1, "price": 19.99 } ], "items_removed": [], "quantity_changes": [] }, "amount_changed": 19.99, "new_total": 109.98 } } ``` ## Webhooks verifizieren Alle Webhooks enthalten einen Signatur-Header zur Prüfung: Node.js-Verifizierung ```javascript const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload, 'utf8') .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(`sha256=${expectedSignature}`) ); } // Express middleware app.post('/webhooks/checkoutos', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-checkoutos-signature']; if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(req.body); // Handle event... res.status(200).send('OK'); }); ``` Python-Verifizierung ```python import hmac import hashlib def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode('utf-8'), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest( f'sha256={expected}', signature ) # Flask example @app.route('/webhooks/checkoutos', methods=['POST']) def handle_webhook(): signature = request.headers.get('X-CheckoutOS-Signature') if not verify_webhook(request.data, signature, WEBHOOK_SECRET): return 'Invalid signature', 401 event = request.get_json() # Handle event... return 'OK', 200 ``` Immer verifizieren Prüfe Webhook-Signaturen immer vor der Verarbeitung. So können Angreifer keine gefälschten Ereignisse an deinen Endpunkt senden. ## Wiederholungsregeln Fehlgeschlagene Zustellungen werden mit exponentiell wachsenden Abständen erneut versucht: Wiederholungsplan ```json { "retry_policy": { "max_attempts": 5, "schedule": [ { "attempt": 1, "delay": "immediately" }, { "attempt": 2, "delay": "5 minutes" }, { "attempt": 3, "delay": "30 minutes" }, { "attempt": 4, "delay": "2 hours" }, { "attempt": 5, "delay": "24 hours" } ], "success_codes": [200, 201, 202, 204], "timeout": "30 seconds" } } ``` ## Webhooks testen Teste deinen Endpunkt vor dem Einsatz: Testereignis senden ```bash curl -X POST "https://api.chargezen.com/v1/webhooks/wh_123/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_type": "upsell.accepted" }' ``` ## Webhook-Protokolle Sieh den Zustellungsverlauf im Dashboard oder über die API an: Webhook-Protokolle abrufen ```bash curl -X GET "https://api.chargezen.com/v1/webhooks/wh_123/logs" \ -H "Authorization: Bearer YOUR_API_KEY" # Response { "data": [ { "id": "log_123", "event_id": "evt_456", "event_type": "upsell.accepted", "status": "delivered", "response_code": 200, "duration_ms": 245, "created_at": "2025-01-16T14:30:00Z" } ] } ``` ## Bewährte Vorgehensweisen Webhook-Tipps * **Schnell antworten** – Innerhalb von 30 Sekunden Status 200 zurückgeben * **Asynchron verarbeiten** – Ereignisse für Hintergrundverarbeitung in eine Warteschlange stellen * **Duplikate behandeln** – Ereignisse können mehrfach zugestellt werden * **Signaturen prüfen** – Vor der Verarbeitung immer validieren * **Fehler überwachen** – Warnungen für fehlgeschlagene Zustellungen einrichten ## Verwandte Themen [ ### Authentifizierung API-Schlüssel verwalten Mehr erfahren ](https://chargezen.com/de/docs/checkoutos/api/authentication)[ ### API-Endpunkte Vollständige Endpunktreferenz Mehr erfahren ](https://chargezen.com/de/docs/checkoutos/api/endpoints) War diese Seite hilfreich? Brauchst du mehr Hilfe? [Support kontaktieren](https://chargezen.com/de/docs/checkoutos/troubleshooting/support)