Warum dein hiapi-Task-Callback nicht ausgelöst wird und wie du das behebst

Warum dein hiapi-Task-Callback nicht ausgelöst wird

Du hast einen Task an POST https://api.hiapi.ai/v1/tasks übermittelt und dabei das callback-Objekt mitgegeben; der Task wurde abgeschlossen (wenn du GET /v1/tasks/{taskId} aufrufst, siehst du status: "success"), aber dein Endpunkt hat nie eine Benachrichtigung über den Endzustand erhalten. Keine einzige Anfrage erreicht deinen Server. Keine Wiederholungsversuche. Nichts in den Logs.

hiapi-Callbacks werden als Server-zu-Server-HTTPS-POST von außerhalb deines Netzwerks zugestellt. Wenn auf diesem Pfad irgendetwas schiefgeht – die URL ist nicht öffentlich erreichbar, TLS lässt sich nicht aushandeln, dein Handler gibt nicht schnell genug 2xx zurück, oder deine eigene Signaturprüfung weist die Anfrage ab – dann ist diese Benachrichtigung aus Sicht deiner Anwendung „stumm“. Die gute Nachricht: Es handelt sich fast immer um eine von wenigen Fehlkonfigurationen, und jede davon lässt sich leicht überprüfen.

Häufige Ursachen (nach Wahrscheinlichkeit sortiert)

1. Die Callback-URL ist nicht öffentlich erreichbar. localhost, 127.0.0.1, eine IP in deinem VPC oder ein abgelaufener ngrok-Tunnel – hiapi kann darauf nicht zugreifen.
2. HTTPS-/TLS-Probleme. Selbstsignierte Zertifikate, abgelaufene Zertifikate, fehlende Zwischenzertifikate oder ein nicht übereinstimmender Hostname. hiapi sendet POSTs ausschließlich an URLs, die mit https:// beginnen, und validiert die Zertifikatskette.
3. Dein Handler gibt nicht innerhalb des Timeouts 2xx zurück. Wenn du in deinem Callback-Handler synchrone, zeitaufwendige Operationen ausführst (Datenbankschreibvorgänge, Bilder herunterladen, Benachrichtigungen senden), läuft die Anfrage ab, bevor du 200 zurückgibst. Aus Sicht von hiapi ist das ein Fehlschlag.
4. Du hast nie einen Webhook Sign Key registriert, und dein Handler weist unsignierte Anfragen ab. Wenn in den Settings kein Signaturschlüssel generiert wurde, wird der von hiapi zugestellte Request-Body ohne Signatur-Header gesendet – jede von dir geschriebene Validierungs-Middleware betrachtet die Anfrage dann als ungültig und verwirft sie.
5. Das callback-Objekt wurde bei der Übermittlung weggelassen. Es ist optional. Wenn du es bei POST /v1/tasks nicht mit angegeben hast, wird nichts ausgelöst. Du musst stattdessen GET /v1/tasks/{taskId} pollen.
6. Der Task läuft noch. Callbacks werden nur im Endzustand ausgelöst (success oder fail). Solange status queued, handling oder archiving ist, wird noch kein Callback gesendet.
7. Der Host der Callback-URL steht auf einer Sperrliste / eine Unternehmensfirewall blockiert ausgehenden Datenverkehr dorthin. Weniger verbreitet, aber wenn du dich in einer streng abgeschotteten Perimeternetzwerkumgebung befindest, lohnt sich eine Prüfung.

Lösung: 7-Schritte-Checkliste

1. Bestätige, dass der Task tatsächlich den Endzustand erreicht hat. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Wenn status queued oder handling ist, wurde der Callback noch nicht ausgelöst – warte zuerst, statt zu debuggen.
2. Bestätige, dass du das callback-Objekt übermittelt hast. Lies den Request-Body erneut, den du an POST /v1/tasks gesendet hast. Wenn callback fehlt, ist das die Antwort – füge es hinzu und übermittle erneut, oder wechsle zum Polling.
3. Teste die Callback-URL von öffentlichem Netz aus. Führe von einer beliebigen Maschine außerhalb deines Netzwerks (ein Smartphone im Mobilfunknetz, eine Cloud-Shell, ein Online-curl-Tool) folgenden Befehl aus: curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json". Du musst von deinem eigenen Server eine HTTP-2xx-Antwort erhalten. Wenn du „Connection refused“, einen DNS-Fehler oder eine beliebige Nicht-2xx-Antwort erhältst, behebe zuerst dieses Problem.
4. Überprüfe die TLS-Zertifikatskette. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Suche nach SSL certificate problem. Wenn du diesen Fehler siehst, installiere die vollständige Zertifikatskette (Leaf-Zertifikat + Zwischenzertifikate) oder verwende ein verwaltetes Zertifikat (Let's Encrypt, CDN, ACM).
5. Gib sofort 200 zurück und verarbeite danach asynchron. Innerhalb deines Handlers: Schreibe die Request-Nutzlast in eine Queue / Datentabelle, gib 200 OK zurück und verarbeite die Arbeit dann in einem Hintergrund-Worker. Lass die Antwort nicht durch langsame nachgelagerte Aufrufe blockieren.
6. Generiere einen Webhook Sign Key und vereinheitliche deine Validierung. Gehe zu /en/dashboard/settings → Webhook Sign Key → Generate und speichere den Schlüssel. Wenn dein Handler die Signatur validiert, verwende den gespeicherten Schlüssel; wenn nicht, deaktiviere die Validierung vorübergehend, bestätige, dass die Zustellung funktioniert, und aktiviere sie dann wieder.
7. Prüfe /en/dashboard/logs. Das Aufrufprotokoll zeigt die Anfrage und ihren Endzustand. Der Abgleich der request_id aus deinem Aufrufprotokoll mit dem, was dein Server tatsächlich empfangen hat (falls überhaupt), ist der schnellste Weg festzustellen, ob „der Callback hiapi verlassen hat“ oder „der Callback meinen Server erreicht hat“.

Minimales Verifizierungsbeispiel

Nutze Folgendes, um deinen API-Schlüssel, den Task-Erstellungspfad und den Callback-Endpunkt end-to-end zu bestätigen. Wähle ein schnelles Bildmodell für den Smoke-Test; laut öffentlicher Dokumentation enthalten Modell-IDs einen Fähigkeits-Suffix:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

Du solltest sofort eine JSON-Antwort erhalten, die eine taskId der Form tk-hiapi-... enthält. Sobald der Task dann success oder fail wird, beobachte deine Server-Logs auf einen eingehenden POST an /hiapi/callback. Wenn der Schritt der Task-Erstellung selbst 401 Unauthorized zurückgibt, liegt das Problem am Schlüssel – siehe Warum hiapi 429 zurückgibt (und was du tun kannst), um zu verstehen, wie der Fehler-Envelope von hiapi funktioniert (dieselbe hiapi_error-Struktur gilt für alle Statuscodes).

Verwandte Links

• API Keys – Prüfe, ob dein Schlüssel gültig ist und den richtigen Berechtigungsumfang hat
• Settings – Generiere oder rotiere deinen Webhook Sign Key
• Call Logs – Bestätige, dass hiapi den Callback gesendet hat und welchen Antwortstatus er erhielt
• API Reference – Vollständige Spezifikation zu POST /v1/tasks und GET /v1/tasks/{id}
• hiapi 429 Rate Limit – Detaillierte Erklärung des Fehler-Envelopes für verwandte Probleme der Art „du hast einen Status erhalten, aber keinen Callback“

FAQ

Wiederholt hiapi fehlgeschlagene Callbacks? Ein Callback gilt nur dann als zugestellt, wenn dein Endpunkt eine 2xx-Antwort zurückgibt. Wenn dein Handler 5xx zurückgibt, ein Timeout auftritt oder der TLS-Handshake fehlschlägt, betrachte den Callback als nicht zugestellt. Das robusteste Muster ist: Für jeden Task, den du mit Callback übermittelt hast, stets das Polling von GET /v1/tasks/{taskId} als Fallback zu nutzen. So verlierst du Ergebnisse auch dann nicht, wenn auf dem Callback-Pfad eine Störung auftritt.

Kann die Callback-URL HTTP statt HTTPS verwenden? Nein. Es werden nur URLs akzeptiert, die mit https:// beginnen. Wenn du lokal testest, verwende einen Tunnel, der TLS für dich terminiert (Cloudflare Tunnel, ngrok, tailscale funnel), und richte den Callback auf den öffentlichen HTTPS-Endpunkt aus.

Warum hat mein Handler den Request-Body erhalten, aber die Signaturprüfung schlägt fehl? Entweder (a) du hast den Webhook Sign Key erst nach der Übermittlung des Tasks generiert – die Anfrage wurde mit dem alten Schlüssel (oder ohne Schlüssel) signiert –, also generiere neu, speichere und übermittle einen neuen Task; oder (b) dein Validierungscode rekonstruiert den kanonischen String anders als hiapi. Erfasse die exakten Bytes des Request-Bodys, den dein Server empfängt, und führe die HMAC-Berechnung erneut auf genau diesen Bytes aus, ohne zwischendurch eine JSON-Neuserialisierung vorzunehmen.

taskId zeigt success, aber ich habe weder einen Callback noch eine Ergebnis-URL erhalten. Rufe erneut GET /v1/tasks/{taskId} auf und prüfe das output-Array. Die URLs in output[*].url sind zeitlich begrenzt (expireAt); lade sie sofort herunter. Callback-Zustellung und URL-Gültigkeitsdauer sind zwei unabhängige Probleme – auch ohne Callback ist der GET-Endpunkt die maßgebliche Quelle.

Ich sehe den Callback in /en/dashboard/logs, aber mein Server hat ihn nie protokolliert. Das bedeutet, das Problem liegt in deinem Perimeternetzwerk, nicht bei hiapi. Häufige Ursachen sind: CDN-/WAF-Regeln, die POST-Anfragen ohne einen für dein Team erkennbaren User-Agent blockieren, eine IP-Allowlist auf der Firewall oder ein Reverse-Proxy, der den Pfad umschreibt. Erlaube den eingehenden POST in deiner Firewall und führe den Test erneut aus.

Verbraucht die Callback-URL mein Kontingent an Ratenbegrenzungen? Nein. Callbacks sind Zustellungen von hiapi an dich und hängen nicht mit deinem POST /v1/tasks-Rate-Budget zusammen.