--- seo_title: API Webhook di Callback Conversioni per Notifiche Job | EnConvert meta_desc: Ricevi un webhook POST tramite callback_url quando i job di conversione asincroni sono completati. Supporta email e polling su GET /v1/convert/batch/{batch_id}. keywords: api webhook callback conversione file, webhook completamento job asincrono, notifica webhook fine conversione file, parametro callback_url, api polling stato batch, email notifica completamento conversione, esempio payload json webhook, testare api webhook callback --- # Callback Webhook di Conversione e Notifiche Job EnConvert ti avvisa quando i job di conversione asincroni e batch sono completati tramite tre meccanismi indipendenti: polling su `GET /v1/convert/batch/{batch_id}`, callback webhook tramite il parametro `callback_url` e notifiche email tramite `notification_email`. Tutti e tre possono essere combinati in un'unica richiesta, e i file completati vengono recuperati tramite gli URL di download presenti nella risposta dello stato del batch. Questa pagina documenta i payload dei callback, i requisiti di consegna e le limitazioni di piano per ciascun metodo.
Solo chiavi private: le notifiche dei job e il polling dello stato del batch sono disponibili solo quando ti autentichi con una chiave API privata (X-API-Key: sk_...). Le chiavi pubbliche non supportano l'elaborazione asincrona o batch.
--- ## Panoramica | Metodo | Parametro / Endpoint | Descrizione | |--------|---------------------|-------------| | Polling | `GET /v1/convert/batch/{batch_id}` | Esegui il polling per lo stato in tempo reale, i conteggi di avanzamento e gli URL di download. | | Email | `notification_email` | Invia un'email di completamento con lo stato del job e un link alla dashboard. | | Webhook | `callback_url` | Invia una richiesta POST con i risultati del job al tuo server. | Tutti e tre i metodi funzionano sia per i job asincroni a URL singolo sia per i job batch multi-URL sugli endpoint [url-to-pdf](/it/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/it/docs/endpoints/convert/web-pages/url-to-screenshot.md), [website-to-pdf](/it/docs/endpoints/convert/web-pages/website-to-pdf.md) e [website-to-screenshot](/it/docs/endpoints/convert/web-pages/website-to-screenshot.md). --- ## Polling dello stato del batch Il modo consigliato per tracciare l'avanzamento del job. Esegui il polling dell'endpoint dello stato del batch con il `batch_id` restituito nella risposta 202 iniziale. ``` GET /v1/convert/batch/{batch_id} X-API-Key: sk_your_private_key ``` ### Risposta ```json { "batch_id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing", "total": 3, "completed": 1, "failed": 0, "in_progress": 2, "output_mode": "individual", "zip_download_url": null, "items": [ { "source_url": "https://example.com/page-1", "status": "Success", "download_url": "https://spaces.example.com/...", "output_file_size": 184320, "duration": "3.12" }, { "source_url": "https://example.com/page-2", "status": "In Progress", "download_url": null, "output_file_size": null, "duration": null } ] } ``` ### Valori di stato | Stato | Significato | |--------|---------| | `processing` | Almeno un URL è ancora in fase di conversione. | | `completed` | Tutti gli URL convertiti con successo. | | `partial` | Tutti gli URL terminati, ma alcuni non sono riusciti. | | `failed` | Tutti gli URL non sono riusciti. | In modalità ZIP (`output_mode: "zip"`), viene fornito uno `zip_download_url` per l'intero archivio una volta completato. In modalità individuale, ogni elemento ha il proprio `download_url`. Per i dettagli completi sullo schema della risposta, consulta [Elaborazione in Batch](/it/docs/guides/batch-processing.md#batch-status-polling). --- ## Notifiche Email Includi il parametro `notification_email` nella tua richiesta per ricevere un'email quando il job viene completato. Se ometti questo parametro, l'email viene inviata per impostazione predefinita all'**indirizzo email del proprietario del progetto**. ### Esempio ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "notification_email": "team@yourcompany.com" }' ``` ### Risposta (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Contenuto dell'email L'email di completamento include: - **Intestazione di stato** con un banner colorato (verde per il successo, rosso per il fallimento) - **Job ID** e **Batch ID** (se fa parte di un batch) - **Testo di stato** (success o failed) - **Testo statico** che indirizza gli utenti a scaricare i file dalla propria dashboard - **Tabella dei task** (solo job batch in modalità ZIP) con le colonne: #, URL (troncato a 50 caratteri), stato e nome del file di output In modalità individuale (inclusi i batch individuali multi-URL), ogni email per singolo URL contiene solo il job ID e lo stato -- nessuna tabella dei task. In modalità ZIP, la singola email del batch include la tabella completa dei task con tutti gli URL e i relativi stati.
Comportamento predefinito: se non includi notification_email nella tua richiesta, l'email di completamento viene inviata automaticamente all'indirizzo email del proprietario del progetto. Per sopprimere completamente le notifiche email, attualmente questo comportamento predefinito non può essere disabilitato.
--- ## Callback Webhook Includi il parametro `callback_url` nella tua richiesta per ricevere un POST webhook quando il job viene completato. Richiede un piano con accesso ai webhook. ### Esempio ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "callback_url": "https://yourapp.com/webhooks/enconvert" }' ``` ### Risposta (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Payload del Callback per URL Singolo / Modalità Individuale In modalità individuale, viene **inviato un POST separato per ogni URL** non appena viene completato: ```json { "job_id": "12345", "status": "success", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_uri": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf", "filename": "example_20260405_123456789.pdf", "file_size": 184320 } ``` Per una conversione non riuscita: ```json { "job_id": "12345", "status": "failed", "batch_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Payload del Callback in Modalità ZIP In modalità ZIP, viene **inviato un singolo POST quando l'intero batch viene completato**: ```json { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "success", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip", "filename": "batch_20260405_123456789.zip", "file_size": 456789, "total_tasks": 3, "successful_tasks": 2, "failed_tasks": 1, "tasks": [ {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"}, {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"}, {"url": "https://invalid-url.example", "status": "failed", "error": "Page load timeout"} ] } ```
Comportamento delle notifiche individuale vs ZIP: in modalità individuale, ricevi N POST webhook separati (uno per URL) e N email separate. In modalità ZIP, ricevi un POST webhook e un'email per l'intero batch. Progetta di conseguenza il tuo gestore di webhook.
--- ## Usare Più Metodi di Notifica Insieme Puoi combinare polling, email e webhook nella stessa richiesta. Tutti e tre funzionano in modo indipendente. ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": [ "https://example.com/page-1", "https://example.com/page-2" ], "notification_email": "team@yourcompany.com", "callback_url": "https://yourapp.com/webhooks/enconvert" }' ``` Dopo l'invio, puoi: 1. **Eseguire il polling** di `GET /v1/convert/batch/{batch_id}` per l'avanzamento in tempo reale 2. **Ricevere un POST webhook** al tuo callback URL quando ogni conversione termina 3. **Ricevere un'email** all'indirizzo specificato quando ogni conversione termina --- ## Parametri di Notifica | Parametro | Tipo | Obbligatorio | Predefinito | Descrizione | Limitazioni di piano | |-----------|------|----------|---------|-------------|-------------| | `notification_email` | `string` | No | Email del proprietario del progetto | Indirizzo email che riceve le notifiche di completamento del job. | -- | | `callback_url` | `string` | No | -- | URL che riceve un POST webhook al completamento. | Richiede l'accesso ai webhook | --- ## Requisiti di Consegna del Webhook | Requisito | Dettaglio | |-------------|--------| | **Metodo** | EnConvert invia una richiesta `POST` con `Content-Type: application/json`. | | **Timeout** | Il tuo endpoint deve rispondere entro **30 secondi**. | | **Codici di successo** | HTTP `200`, `201`, `202` o `204` sono trattati come consegna riuscita. | | **Tentativi** | Nessun tentativo in caso di fallimento. Se la consegna del webhook fallisce (risposta non riuscita o timeout), i risultati restano comunque disponibili tramite il polling dello stato del batch. | | **Autenticazione** | Non viene inviato alcun header di autenticazione. Convalida il `batch_id` rispetto ai tuoi record se necessario. | --- ## Limitazioni in Base al Piano di Abbonamento | Funzionalità | Founding | Indie | Studio | Enterprise | |---------|------|---------|-----|------------| | Modalità asincrona | No | Sì | Sì | Sì | | Polling dello stato del batch | No | Sì | Sì | Sì | | Notifiche email | No | Sì | Sì | Sì | | Callback webhook (`callback_url`) | No | No | Sì | Sì |
Nota: le notifiche email non sono soggette a una limitazione di funzionalità separata -- sono disponibili per qualsiasi utente con chiave API privata che disponga dell'accesso asincrono. Il parametro notification_email non richiede una funzionalità di piano specifica. I callback webhook (callback_url) richiedono la funzionalità has_webhook, disponibile sui piani Studio e superiori.
--- ## Testare i Webhook Durante lo sviluppo, usa [webhook.site](https://webhook.site) per generare un callback URL temporaneo per i test: ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "callback_url": "https://webhook.site/your-unique-id" }' ``` Visita la tua dashboard di webhook.site per ispezionare il payload esatto del callback una volta completato il job. ## Domande frequenti ### Come ricevo un callback webhook quando un job di conversione file è completato? Includi il parametro `callback_url` nella tua richiesta con una chiave API privata. EnConvert invia un `POST` con `Content-Type: application/json` a quell'URL quando il job viene completato. I callback webhook richiedono un piano con accesso ai webhook (Studio, Production o Enterprise). ### EnConvert ritenta le consegne webhook non riuscite? No. Il tuo endpoint deve rispondere entro 30 secondi con HTTP `200`, `201`, `202` o `204`. Se la consegna fallisce, i risultati restano disponibili tramite il polling dello stato del batch su `GET /v1/convert/batch/{batch_id}`. ### Posso usare insieme le notifiche email, webhook e polling? Sì. `notification_email`, `callback_url` e il polling dello stato funzionano tutti in modo indipendente e possono essere combinati nella stessa richiesta. Se `notification_email` viene omesso, l'email di completamento viene inviata di default all'indirizzo email del proprietario del progetto. ### Perché ricevo un webhook per ogni URL invece di uno per l'intero batch? In modalità individuale ricevi N POST webhook separati (uno per URL) e N email separate. Per ricevere un solo webhook e una sola email per l'intero batch, usa la modalità ZIP, che invia un unico POST con `total_tasks`, `successful_tasks`, `failed_tasks` e un array `tasks`. ### Come posso testare i callback webhook durante lo sviluppo? Usa webhook.site per generare un URL temporaneo e passalo come `callback_url` nella tua richiesta. La dashboard di webhook.site mostra il payload JSON esatto che EnConvert consegna quando il job viene completato.