Authentifizierung

Die CheckYout Partner API verwendet zwei Authentifizierungsmechanismen: einen API-Key für Ihre Anfragen an CheckYout und ein Webhook-Secret zur Verifizierung der Events, die CheckYout an Sie sendet.

API-Key

Der API-Key authentifiziert Ihre Anfragen an die CheckYout API (z.B. POST /api/v1/notify). Er wird im CheckYout-Dashboard unter Einstellungen → API-Keys erstellt.

Format

Eigenschaft	Wert
Prefix	`cyo_`
Länge	Prefix + 32 hexadezimale Zeichen
Beispiel	`cyo_a1b2c3d4e5f6...`
Speicherung	SHA-256-gehasht (Klartext wird nur einmal angezeigt)

Nur einmal sichtbar

Der API-Key wird bei der Erstellung einmalig im Klartext angezeigt. Danach speichert CheckYout nur den SHA-256-Hash. Verlieren Sie den Key, müssen Sie einen neuen erstellen.

Verwendung

Senden Sie den API-Key im X-API-Key-Header mit jeder Anfrage:

curl -X POST https://checkyout.app/api/v1/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyo_IhrApiKey" \
  -d '{"device_id": "...", "phone": "+41..."}'

Webhook-Signatur

Wenn Sie beim API-Key ein Webhook-Secret hinterlegt haben, signiert CheckYout jeden Webhook mit HMAC-SHA256. Die Signatur wird im Header X-CheckYout-Signature als Hexadezimal-String mitgesendet.

Header	Wert
`X-CheckYout-Signature`	HMAC-SHA256 Hex-Digest des JSON-Body mit Ihrem Webhook-Secret

Signatur verifizieren

Berechnen Sie den HMAC-SHA256 des rohen Request-Body mit Ihrem Webhook-Secret und vergleichen Sie das Ergebnis mit dem Wert im Header:

const crypto = require('crypto');

function verifySignature(body, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In Ihrem Webhook-Handler:
app.post('/webhooks/checkyout', (req, res) => {
  const signature = req.headers['x-checkyout-signature'];
  const secret = process.env.CHECKYOUT_WEBHOOK_SECRET;

  if (secret && signature) {
    if (!verifySignature(req.body, secret, signature)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }

  // Event verarbeiten...
  res.status(200).json({ received: true });
});

import hmac
import hashlib
import json

def verify_signature(body: dict, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        json.dumps(body, separators=(",", ":")).encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In Ihrem Webhook-Handler (Flask):
@app.route("/webhooks/checkyout", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-CheckYout-Signature")
    secret = os.environ.get("CHECKYOUT_WEBHOOK_SECRET")

    if secret and signature:
        if not verify_signature(request.json, secret, signature):
            return jsonify({"error": "Invalid signature"}), 401

    # Event verarbeiten...
    return jsonify({"received": True}), 200

<?php
function verifySignature(string $body, string $secret, string $signature): bool {
    $expected = hash_hmac('sha256', $body, $secret);
    return hash_equals($expected, $signature);
}

// In Ihrem Webhook-Handler:
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CHECKYOUT_SIGNATURE'] ?? '';
$secret = getenv('CHECKYOUT_WEBHOOK_SECRET');

if ($secret && $signature) {
    if (!verifySignature($body, $secret, $signature)) {
        http_response_code(401);
        echo json_encode(['error' => 'Invalid signature']);
        exit;
    }
}

$event = json_decode($body, true);
// Event verarbeiten...

http_response_code(200);
echo json_encode(['received' => true]);

Hinweis zur Python-Signatur

CheckYout serialisiert den Body mit JSON.stringify() (JavaScript). Stellen Sie sicher, dass Ihre Serialisierung dasselbe Format erzeugt — ohne zusätzliche Leerzeichen. Im Zweifelsfall verifizieren Sie gegen den rohen Request-Body statt gegen eine Neu-Serialisierung.

Best Practices

Speichern Sie den API-Key in einer Umgebungsvariable, nie im Quellcode.
Rotieren Sie den Key sofort bei Verdacht auf Kompromittierung.
Verwenden Sie timingSafeEqual (oder Äquivalent) beim Signaturvergleich, um Timing-Attacken zu verhindern.
Verifizieren Sie die Webhook-Signatur vor der Verarbeitung des Events.
Loggen Sie fehlgeschlagene Signaturverifikationen für Ihre Sicherheitsüberwachung.

Nächster Schritt: Webhooks im Detail