Skip to main content

Panoramica

Invece di effettuare polling su GET /jobs/{id} ripetutamente, puoi fornire un URL webhook per ricevere una richiesta POST quando il tuo job si completa. È più efficiente e riduce le chiamate API non necessarie.

Utilizzo dei webhook

Aggiungi l’intestazione X-Webhook-URL a qualsiasi richiesta di generazione. Quando il job raggiunge uno stato terminale (completato, fallito o cancellato), l’API invierà una richiesta POST al tuo URL con i dati completi del job.

Payload del webhook

Quando il job si completa, l’URL webhook riceve una richiesta POST con i dati del job:

Buone pratiche

Rispondi rapidamente - Restituisci prontamente un codice di stato 2xx. Se necessario, elabora i dati del webhook in modo asincrono.
Valida il payload - Verifica che il job_id corrisponda a un job che hai avviato prima di elaborare i risultati.
  • Usa endpoint HTTPS per la sicurezza
  • Implementa l’idempotenza in caso di consegne duplicate
  • Registra le ricezioni dei webhook per il debug

Webhook vs Polling

Usa i webhook quando hai un server in grado di ricevere richieste HTTP. Usa il polling per applicazioni lato client o quando non puoi esporre un endpoint pubblico.

Prossimi passi

Ciclo di vita del job

Scopri gli stati dei job e il polling dello stato

Esempi di codice

Vedi esempi completi con gestione dei webhook