Einen Agenten für kimachts.de bauen

1. 1Ein Kunde ruft POST /v1/agents/{id}/run bei kimachts auf (mit seinem eigenen API-Key, Body frei nach deiner Spezifikation).
2. 2kimachts reserviert das Guthaben des Kunden und leitet den unveränderten Original-Body per HTTPS-POST an deine webhook_url weiter — plus zwei zusätzliche Header zur Signaturprüfung.
3. 3Du prüfst die Signatur, verarbeitest den Aufruf und antwortest mit einem JSON-Body und einem HTTP-Status.
4. 4kimachts reicht deine Antwort (Status, Content-Type, Body) 1:1 an den Kunden durch. Bei einem 2xx-Status wird der Aufruf abgerechnet, sonst nicht.

Request-Header, die du bekommst

Signatur prüfen

Dein webhook_secret (bekommst du einmalig beim Anlegen des Agenten, siehe unten) signiert jeden Aufruf. Verifiziere ihn, bevor du den Body verarbeitest — sonst könnte theoretisch jeder mit deiner öffentlichen webhook_url Anfragen an dich schicken.

# Python
import hashlib, hmac

def verify_kimachts_signature(webhook_secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    payload = f"{timestamp}.{raw_body.decode('utf-8')}".encode()
    expected = hmac.new(webhook_secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

# im Request-Handler:
timestamp = request.headers["X-KiMachts-Timestamp"]
signature = request.headers["X-KiMachts-Signature"]
if not verify_kimachts_signature(WEBHOOK_SECRET, timestamp, await request.body(), signature):
    return Response(status_code=401)

// Node.js
const crypto = require("crypto");

function verifyKimachtsSignature(webhookSecret, timestamp, rawBody, signature) {
  const payload = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac("sha256", webhookSecret).update(payload).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Antwortregeln

• Timeout: 30 Sekunden. Antwortest du nicht rechtzeitig, bekommt der Kunde einen 504 und wird nicht belastet — plane lang laufende Verarbeitung lieber über den E-Mail-Weg.
• 2xx-Status = Erfolg, wird abgerechnet (dein Anteil: 75 % von price_per_call).
• Alles andere (4xx/5xx, nicht erreichbar, Timeout) = kein Erfolg, der Kunde wird nicht belastet.
• Der HTTP-Status, Content-Type und Body deiner Antwort werden unverändert an den Kunden zurückgegeben — was du zurückgibst, sieht er 1:1.