Webhooks: CheckoutOS-Doku

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

Zu Webhooks wechseln

Gehe zu CheckoutOS → Settings → Webhooks.

Endpunkt hinzufügen

Klicke auf „Add Webhook Endpoint“.

URL eingeben

Gib die HTTPS-URL für den Empfang der Ereignisse ein.

Ereignisse wählen

Wähle die zu abonnierenden Ereignisse.

Speichern

Speichere und notiere den Signaturschlüssel.

Webhook über die API erstellen

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

{
  "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

{
  "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

{
  "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

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

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

{
  "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

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

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

Webhooks