HiAPI-Callbacks kommen nicht an? Diagnose- und Reparaturanleitung für Webhook-Zustellprobleme

Du hast beim Einreichen einer Aufgabe an POST https://api.hiapi.ai/v1/tasks die Angabe callback.url mitgeschickt, damit HiAPI dich nach Abschluss der Aufgabe aktiv per POST benachrichtigt. Aber obwohl die Aufgabe in GET /v1/tasks/{taskId} bereits den Status success hat, empfängt dein Callback-Endpunkt keine einzige Benachrichtigung. Solche Probleme liegen in den meisten Fällen nicht an HiAPI selbst, sondern daran, ob die Callback-Adresse erreichbar ist, ob der Empfänger wie vereinbart mit 2xx antwortet und ob Polling und Callback sich gegenseitig überholen. Im Folgenden gehen wir die echte Callback-Vereinbarung Punkt für Punkt durch und geben sofort umsetzbare Reparaturschritte.

Wenn deine Aufgabe lange keinen Endzustand erreicht (data.status bleibt lange bei queued/handling/archiving), handelt es sich um eine andere Problemklasse – siehe Diagnose- und Wiederholungsanleitung für hängende oder abgelaufene HiAPI-Aufgaben. Dieser Artikel behandelt nur den Fall, dass die Aufgabe bereits abgeschlossen ist, aber keine Callback-Benachrichtigung ankommt.

Symptome

Typisch ist, dass auf der Aufgabenseite alles normal ist: GET /v1/tasks/{taskId} liefert data.status als success (oder fail), aber im Log deines öffentlich erreichbaren Callback-Endpunkts findet sich kein einziger POST-Eintrag von HiAPI; oder du empfängst gelegentlich, verlierst aber häufig; oder dieselbe taskId wird zweimal zugestellt und von deiner Deduplizierungslogik als Anomalie behandelt.

Zunächst eine Tatsache: Callback ist nur eine Art, Ergebnisse abzuholen, kein ausschließlicher Kanal. Asynchrone Aufgaben von HiAPI lassen sich immer per aktivem Polling über GET /v1/tasks/{taskId} bis zum Endzustand abfragen; Callback (Webhook) erspart dir nur das Polling. Daher bedeutet "Callback kommt nicht an" nicht "Ergebnis ist nicht abrufbar". Bestätige zuerst per Polling, dass die Aufgabe selbst in Ordnung ist, und lokalisiere dann das Zustellproblem.

Die tatsächliche Callback-Vereinbarung (erst abgleichen, dann Fehler suchen)

Bei der Callback-Registrierung ist callback ein Top-Level-Feld von POST /v1/tasks, gleichrangig mit model und input; es darf nicht in input gesteckt werden:

{
  "model": "gpt-image-2",
  "input": { "prompt": "a calm blue data center" },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Einige unbedingt zu merkende Punkte:

• callback.url muss eine öffentlich erreichbare http(s)-URL sein; HiAPI initiiert von außen einen POST dorthin.
• callback.when akzeptiert derzeit nur final: einmalige Zustellung, wenn die Aufgabe den Endzustand erreicht; sowohl success als auch fail lösen sie aus. Es gibt keine Callbacks nach Fortschritt oder in Phasen.
• Zustellmethode ist POST + Content-Type: application/json; der Request-Body ist identisch mit dem data-Feld von GET /v1/tasks/{taskId}, also dem Aufgaben-Detailobjekt mit status, output, error, taskId, created, completed usw.
• Bei Zustellfehlern (nicht 2xx / Timeout / Netzwerkfehler) wird nach folgendem Muster erneut zugestellt: sofort → +1 Minute → +5 Minuten → +20 Minuten, maximal 4-mal; schlagen alle 4 Versuche fehl, wird nicht weiter wiederholt, und der Status der Aufgabe selbst wird nicht beeinflusst.
• Endzustands-Callbacks haben At-least-once-Semantik, nicht Exactly-once. Dieselbe taskId kann mehrfach zugestellt werden; der Empfänger muss anhand der taskId idempotent deduplizieren.

Verbindliche Details gemäß offizieller Dokumentation: Aufgabe erstellen und callback-Feld, Übersicht der asynchronen API (Callback-Wiederholungen und Idempotenz).

Häufige Ursachen (nach Trefferwahrscheinlichkeit sortiert)

1. Callback-Adresse nicht öffentlich erreichbar (am häufigsten)

Angegeben als http://localhost:3000/..., interne IP oder eine Domain, die nur im internen DNS auflöst. HiAPI kann deinen lokalen Rechner aus dem öffentlichen Netz nicht erreichen und kann natürlich nichts zustellen. Bei lokaler Entwicklung tritt dies am häufigsten auf.

2. Empfänger gibt kein 2xx zurück

Der Handler wirft eine Ausnahme, gibt eine 3xx-Weiterleitung zurück, wird von einer Auth-Middleware als 401/403 blockiert oder liefert 5xx. HiAPI betrachtet nur HTTP 2xx als erfolgreiche Zustellung; alles andere führt zu Wiederholungen, und nach Erschöpfung des Wiederholungsfensters äußert sich das als "kommt nicht an".

3. Verarbeitungs-Timeout

Der Handler erledigt zuerst aufwändige Arbeit (Herunterladen von Artefakten, Umkopieren in Objektspeicher, Schreiben in die Datenbank, Versenden von Nachrichten) und gibt erst dann 200 zurück; dauert das zu lange, wird ein Timeout erkannt und eine Wiederholung ausgelöst. In Summe wirkt es wie Paketverlust.

4. callback in input abgelegt

Es ist ein Top-Level-Feld; in input abgelegt wird es nicht als Callback-Registrierung erkannt. Außerdem ist input je Modell ein striktes Schema; das Einfügen unbekannter Schlüssel führt in der Regel bereits beim Einreichen zu einem synchronen Fehler invalid input: <root>: additional properties 'callback' not allowed – die Aufgabe wurde gar nicht erfolgreich eingereicht.

5. when mit einem anderen Wert als final gefüllt

Derzeit wird nur final unterstützt; andere Werte werden abgelehnt.

6. Polling und Callback überholen sich

Du hast sowohl Polling aktiviert als auch auf Callback gewartet; das Polling erhält zuerst den Endzustand und schließt den lokalen Aufgaben-Datensatz. Wenn der Callback ankommt, findet er keinen passenden Datensatz und wird als "nicht empfangen" gewertet.

7. Zertifikat- oder WAF-Blockierung

Die Callback-Adresse verwendet ein selbstsigniertes oder abgelaufenes Zertifikat, oder eine WAF blockiert den anonymen POST ohne üblichen User-Agent und ohne deine eigenen Auth-Header als verdächtigen Traffic.

Reparaturschritte

1. Zunächst bestätigen, dass die Aufgabe selbst in Ordnung ist. Prüfe mit GET /v1/tasks/{taskId} das Feld data.status; ist es success/fail, ist die Aufgabe im Endzustand und das Problem liegt im Zustellpfad; steht sie noch nicht im Endzustand, gehört es zu einer anderen Problemklasse (siehe Hänge-Diagnose am Anfang).
2. Ersetze die Callback-Adresse durch eine öffentliche https-Domain. Führe von einer externen Maschine aus curl -i -X POST https://your-domain.com/hiapi/callback -d '{}' aus und bestätige, dass eine Verbindung möglich ist und 2xx zurückkommt. Für localhost-Debugging mappe den lokalen Port über einen öffentlichen Tunnel nach außen.
3. Callback zuerst zuverlässig speichern, dann schnell 2xx zurückgeben. Schreibe den Callback-Inhalt zuerst in die Datenbank oder eine persistente Queue (dieser Schritt muss schnell sein); erst nach Erfolg 2xx zurückgeben. Aufwändige Arbeiten wie Herunterladen und Umkopieren in den Hintergrund auslagern. Gib kein 200 zurück, bevor der Datensatz persistiert ist: Stürzt der Prozess danach ab, ist dieser Callback verloren, und HiAPI wird nach Erhalt von 2xx nicht erneut zustellen. Befreie zugleich diesen Pfad von der Auth-Middleware, denn HiAPIs Callback enthält keine eigenen Auth-Header.
4. Prüfe Position und Wert von callback. Stelle sicher, dass es sich auf Top-Level des Request-Bodys befindet (gleichrangig mit model, input), dass url eine öffentliche http(s)-Adresse und when final ist.
5. Idempotente Deduplizierung anhand taskId. Prüfe bei Empfang des Callbacks zuerst lokal, ob diese taskId bereits verarbeitet wurde; erst wenn nicht, persistieren / Folgeaktionen auslösen. Unter At-least-once-Semantik ist mehrfaches Eintreffen normal; behandle Wiederholungen nicht als Anomalie und verwirf sie nicht.
6. Füge ein Fallback-Polling hinzu. Für taskIds, deren Callback nach erwarteter Zeit nicht eingetroffen ist, frage den Endzustand aktiv per GET /v1/tasks/{taskId} nach. Callback ist eine Optimierung, Polling die Grundabsicherung; beide werden über dieselbe Idempotenzlogik zusammengeführt.
7. Artefakte schnell umkopieren. Die output[].url im Callback-Body ist ein temporärer Link (storage ist temp, expireAt ist eine Unix-Zeit, läuft nach etwa 7 Tagen ab). Lade ihn sofort herunter oder kopiere ihn in deinen eigenen Speicher; speichere keine Hotlinks.

Minimales Verifikationsbeispiel

Lass den Callback zunächst beiseite und beweise mit "Einreichen + Polling", dass dein Key und die Anbindung selbst funktionieren (mit nackter Modell-ID):

# 1. Aufgabe einreichen
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"a calm blue data center"}}'
# → {"code":200,"message":"success","data":{"taskId":"tk-hiapi-..."}}

# 2. Mit zurückgegebener taskId den Endzustand pollen
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxx \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# → data.status läuft von queued/handling/archiving zu success (mit output) oder fail (mit error)

Wenn das Einreichen bereits HTTP 401 + {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} zurückgibt, ist der API-Key falsch; prüfe ihn in der Konsole und versuche es erneut. Nachdem die Anbindung bestätigt ist, füge dem POST-Body das Top-Level-callback hinzu und prüfe den Empfänger gemäß den obigen Reparaturschritten Punkt für Punkt.

FAQ

Ich empfange den Callback durchgehend nicht, aber die Aufgabe war erfolgreich – kann ich das Ergebnis trotzdem abrufen? Ja. Jederzeit kannst du mit GET /v1/tasks/{taskId} data.status und data.output lesen; ein verlorener Callback hindert dich nicht am aktiven Abrufen des Ergebnisses.

Wie oft und in welchen Abständen wird ein Callback wiederholt? Bei nicht 2xx / Timeout / Netzwerkfehler wird mit sofort → +1 Minute → +5 Minuten → +20 Minuten erneut zugestellt, maximal 4-mal. Nach 4 Fehlversuchen wird nicht weiter wiederholt, und der success/fail-Status der Aufgabe selbst bleibt unberührt.

Ist es normal, zwei Callbacks für dieselbe Aufgabe zu erhalten? Ja. Endzustands-Callbacks haben "At-least-once"-Semantik; dedupliziere idempotent anhand der taskId und betrachte mehrfache Zustellung nicht als Fehler.

Wie empfange ich Callbacks bei lokaler Entwicklung? localhost und interne Adressen kann HiAPI nicht erreichen. Entweder mappe deinen lokalen Port über einen öffentlichen Tunnel nach außen, oder verwende in der lokalen Phase direkt Polling und schalte erst nach dem Deployment auf Callback um.

Welche Felder enthält der Callback-Request-Body? Er ist identisch mit dem data von GET /v1/tasks/{taskId} und enthält taskId, status, output (Artefakt-Array bei Erfolg), error (code und message bei Fehlschlag), created, completed usw. Details siehe Dokumentation zu Aufgabendetails.

Wird bei nicht empfangenem Callback mehr abgerechnet? Nein. Eine fehlgeschlagene Aufgabe wird nicht abgerechnet; reserviertes Guthaben wird zurückerstattet. Ob die Callback-Zustellung erfolgreich ist, ändert das Abrechnungsergebnis der Aufgabe nicht; abgerechnet wird nur danach, ob die Aufgabe letztlich erfolgreich generiert wurde.