Perché i callback dei tuoi task hiapi non vengono attivati e come risolverlo

Perché i callback dei tuoi task hiapi non vengono attivati

Hai inviato un task a POST https://api.hiapi.ai/v1/tasks includendo un oggetto callback; il task è stato completato (quando esegui GET /v1/tasks/{taskId} vedi status: "success"), ma il tuo endpoint non ha mai ricevuto la notifica di stato finale. Nessuna richiesta è arrivata al tuo server. Nessun nuovo tentativo. Niente nei log.

I callback hiapi vengono consegnati come POST HTTPS da server a server dall'esterno della tua rete. Se un qualsiasi anello di questa catena si rompe — l'URL non è raggiungibile da Internet pubblico, il TLS non riesce a negoziare, il tuo handler non restituisce 2xx abbastanza rapidamente, oppure la tua verifica della firma rifiuta la richiesta — allora, dal punto di vista della tua applicazione, la notifica è "silenziosa". La buona notizia: si tratta quasi sempre di uno dei pochi errori di configurazione, e ognuno è facile da verificare.

Cause comuni (in ordine di probabilità)

1. L'URL di callback non è raggiungibile da Internet pubblico. localhost, 127.0.0.1, un IP all'interno del tuo VPC o un tunnel ngrok scaduto — hiapi non riesce a raggiungerli.
2. Problemi HTTPS / TLS. Certificati autofirmati, certificati scaduti, certificati intermedi mancanti o nome host non corrispondente. hiapi invia POST solo verso URL che iniziano con https:// e verifica la catena di certificati.
3. Il tuo handler non restituisce 2xx entro il timeout. Se nel tuo handler di callback esegui operazioni sincrone lente (scritture su database, download di immagini, invio di notifiche), la richiesta va in timeout prima che tu restituisca 200. Dal punto di vista di hiapi, questo è un fallimento.
4. Non hai mai registrato la Webhook Sign Key, e il tuo handler rifiuta le richieste non firmate. Se non hai generato una chiave di firma nelle Impostazioni, il corpo della richiesta consegnata da hiapi non avrà l'header di firma — qualsiasi middleware di verifica tu abbia scritto considererà quella richiesta non valida e la scarterà.
5. Hai omesso l'oggetto callback al momento dell'invio. È opzionale. Se non lo hai incluso quando hai fatto POST /v1/tasks, non ci sarà nulla che si attivi. Devi invece fare polling con GET /v1/tasks/{taskId}.
6. Il task è ancora in esecuzione. I callback si attivano solo in stato finale (success o fail). Quando status è queued, handling o archiving, il callback non viene ancora inviato.
7. L'host dell'URL di callback è nella lista di blocco / il firewall aziendale blocca il traffico in uscita verso di esso. Meno comune, ma vale la pena verificarlo se ti trovi in un ambiente di rete perimetrale rigoroso.

Come risolvere: checklist in 7 passi

1. Conferma che il task abbia effettivamente raggiunto lo stato finale. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Se status è queued o handling, il callback non è ancora stato attivato — aspetta, non fare debug.
2. Conferma di aver inviato l'oggetto callback. Rileggi il corpo della richiesta che hai inviato a POST /v1/tasks. Se manca callback, la risposta è questa — aggiungilo e invia di nuovo, oppure passa al polling.
3. Testa l'URL di callback da Internet pubblico. Da qualsiasi macchina esterna alla tua rete (uno smartphone con rete cellulare, una shell cloud, uno strumento curl online), esegui curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json". Devi ricevere una risposta HTTP 2xx dal tuo server. Se ottieni connessione rifiutata, errori DNS o qualsiasi risposta diversa da 2xx, risolvi prima questo problema.
4. Verifica la catena del certificato TLS. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Cerca SSL certificate problem. Se vedi questo errore, installa la catena completa dei certificati (certificato foglia + intermedi), oppure usa certificati gestiti (Let's Encrypt, CDN, ACM).
5. Restituisci 200 immediatamente, poi elabora in modo asincrono. All'interno del tuo handler: scrivi il payload della richiesta in una coda / tabella dati, restituisci 200 OK, poi elabora il lavoro in un worker in background. Non lasciare che la risposta venga bloccata da chiamate downstream lente.
6. Genera la Webhook Sign Key e uniforma il tuo metodo di verifica. Vai su /en/dashboard/settings → Webhook Sign Key → Generate, salva la chiave. Se il tuo handler verifica la firma, usa la chiave salvata; se non la verifica, disattiva temporaneamente la verifica, conferma che la consegna funzioni e poi riattivala.
7. Controlla /en/dashboard/logs. I log delle chiamate mostrano la richiesta e il suo stato finale. Confrontare il request_id nei tuoi log delle chiamate con ciò che il tuo server ha effettivamente ricevuto (se qualcosa) è il modo più rapido per capire se "il callback è uscito da hiapi" e se "il callback è arrivato al mio server".

Esempio minimo di verifica

Usa quanto segue per confermare end-to-end la tua chiave API, il percorso di creazione del task e l'endpoint di callback. Scegli un modello di immagini veloce per lo smoke test; secondo la documentazione pubblica, l'ID del modello include il suffisso di capacità:

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"}
  }'

Dovresti ricevere immediatamente una risposta JSON contenente un taskId nella forma tk-hiapi-.... Poi, una volta che il task passa a success o fail, osserva i log del tuo server per verificare se c'è un POST in ingresso verso /hiapi/callback. Se il passo di creazione del task stesso restituisce 401 Unauthorized, allora il problema è la chiave — consulta Perché hiapi restituisce 429 (e cosa fare) per capire come funziona il meccanismo dell'envelope di errore di hiapi (la stessa struttura hiapi_error si applica a tutti i codici di stato).

Link correlati

• API Keys — verifica che la tua chiave sia valida e abbia gli scope corretti
• Settings — genera o ruota la tua Webhook Sign Key
• Call Logs — conferma che hiapi abbia inviato il callback e lo stato della risposta
• API Reference — specifiche complete di POST /v1/tasks e GET /v1/tasks/{id}
• Limite di rate 429 di hiapi — approfondimento sull'envelope di errore per problemi correlati del tipo "hai ricevuto uno stato ma nessun callback"

FAQ

hiapi ritenta i callback falliti? Un callback è considerato consegnato solo se il tuo endpoint restituisce una risposta 2xx. Se il tuo handler restituisce 5xx, va in timeout o la stretta di mano TLS fallisce, considera il callback come non consegnato. Il modello più robusto è: per qualsiasi task inviato con un callback, usa sempre il polling di GET /v1/tasks/{taskId} come fallback. Così, anche se si verifica un guasto sul percorso del callback, non perdi il risultato.

L'URL di callback può usare HTTP invece di HTTPS? No. Sono accettati solo URL che iniziano con https://. Se stai testando in locale, usa un tunnel che termina il TLS per te (Cloudflare Tunnel, ngrok, tailscale funnel) e punta il callback a un endpoint HTTPS pubblico.

Perché il mio handler riceve il corpo della richiesta ma la verifica della firma fallisce? O (a) hai generato la Webhook Sign Key dopo aver inviato il task — la richiesta è stata firmata con la vecchia chiave (o senza chiave) — quindi rigenera, salva e invia un nuovo task; oppure (b) il tuo codice di verifica ricostruisce la stringa canonica in modo diverso da hiapi. Registra i byte esatti del corpo che il tuo server ha ricevuto e riesegui l'HMAC su quegli stessi byte esatti, senza alcuna riserializzazione JSON nel mezzo.

taskId mostra success, ma non ho ricevuto il callback né l'URL del risultato. Richiedi di nuovo GET /v1/tasks/{taskId} e controlla l'array output. Gli URL in output[*].url hanno una scadenza (expireAt); scaricali subito. La consegna del callback e la validità temporale dell'URL sono due problemi distinti — anche senza callback, l'endpoint GET è la fonte di verità.

Ho visto il callback in /en/dashboard/logs, ma il mio server non lo ha mai registrato. Questo indica un problema nella tua rete perimetrale, non in hiapi. Le cause comuni includono: regole CDN / WAF che bloccano POST senza un User-Agent riconoscibile dal tuo team, un'allowlist di IP sul firewall, oppure il tuo reverse proxy che riscrive il percorso. Consenti quel POST in ingresso sul firewall e riprova.

L'URL di callback consuma il limite di rate del mio account? No. I callback sono consegne da hiapi a te e non sono correlate al tuo budget di rate di POST /v1/tasks.