--- seo_title: API de callbacks webhook pour notifications de tâches | EnConvert meta_desc: Recevez un POST webhook via callback_url à la fin des tâches asynchrones. Compatible aussi avec e-mails et l'interrogation de GET /v1/convert/batch/{batch_id}. keywords: api rappel webhook conversion, webhook fin de tâche asynchrone, recevoir un webhook quand une conversion se termine, paramètre callback_url, api interrogation statut d'un lot, notification e-mail fin de conversion, exemple charge utile json webhook, tester un rappel webhook api --- # Rappels webhook de conversion et notifications de tâches EnConvert vous notifie lorsque les tâches de conversion asynchrones et par lot se terminent, via trois mécanismes indépendants : l'interrogation de `GET /v1/convert/batch/{batch_id}`, les rappels webhook via le paramètre `callback_url`, et les notifications par e-mail via `notification_email`. Les trois peuvent être combinés dans une seule requête, et les fichiers terminés sont récupérés via les URL de téléchargement présentes dans la réponse de statut du lot. Cette page documente les charges utiles de rappel, les exigences de livraison et les restrictions par forfait pour chaque méthode.
Clés privées uniquement : Les notifications de tâches et l'interrogation du statut d'un lot ne sont disponibles que lors de l'authentification avec une clé API privée (X-API-Key: sk_...). Les clés publiques ne prennent pas en charge le traitement asynchrone ou par lot.
--- ## Vue d'ensemble | Méthode | Paramètre / Endpoint | Description | |--------|---------------------|-------------| | Polling | `GET /v1/convert/batch/{batch_id}` | Interroge le statut en temps réel, les compteurs de progression et les URL de téléchargement. | | Email | `notification_email` | Envoie un e-mail de fin avec le statut de la tâche et un lien vers le tableau de bord. | | Webhook | `callback_url` | Envoie une requête POST avec les résultats de la tâche vers votre serveur. | Les trois méthodes fonctionnent aussi bien pour les tâches asynchrones à URL unique que pour les tâches par lot à URL multiples, sur les endpoints [url-to-pdf](/fr/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/fr/docs/endpoints/convert/web-pages/url-to-screenshot.md), [website-to-pdf](/fr/docs/endpoints/convert/web-pages/website-to-pdf.md) et [website-to-screenshot](/fr/docs/endpoints/convert/web-pages/website-to-screenshot.md). --- ## Interrogation du statut d'un lot La méthode recommandée pour suivre la progression d'une tâche. Interrogez l'endpoint de statut du lot avec le `batch_id` renvoyé dans la réponse initiale 202. ``` GET /v1/convert/batch/{batch_id} X-API-Key: sk_your_private_key ``` ### Réponse ```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 } ] } ``` ### Valeurs de statut | Statut | Signification | |--------|---------| | `processing` | Au moins une URL est encore en cours de conversion. | | `completed` | Toutes les URL ont été converties avec succès. | | `partial` | Toutes les URL sont terminées, mais certaines ont échoué. | | `failed` | Toutes les URL ont échoué. | En mode ZIP (`output_mode: "zip"`), un `zip_download_url` est fourni pour l'archive entière une fois terminée. En mode individuel, chaque élément a son propre `download_url`. Pour tous les détails du schéma de réponse, consultez [Traitement par lot](/fr/docs/guides/batch-processing.md#batch-status-polling). --- ## Notifications par e-mail Incluez le paramètre `notification_email` dans votre requête pour recevoir un e-mail lorsque la tâche se termine. Si vous omettez ce paramètre, l'e-mail est envoyé par défaut à **l'adresse e-mail du propriétaire du projet**. ### Exemple ```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" }' ``` ### Réponse (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Contenu de l'e-mail L'e-mail de fin inclut : - **En-tête de statut** avec une bannière colorée (vert pour succès, rouge pour échec) - **ID de tâche** et **ID de lot** (si la tâche fait partie d'un lot) - **Texte de statut** (succès ou échec) - **Texte statique** dirigeant les utilisateurs vers le téléchargement des fichiers depuis leur tableau de bord - **Tableau des tâches** (uniquement pour les tâches par lot en mode ZIP) avec les colonnes : #, URL (tronquée à 50 caractères), statut, et nom de fichier de sortie En mode individuel (y compris les lots individuels à URL multiples), chaque e-mail par URL contient uniquement l'ID de tâche et le statut -- pas de tableau des tâches. En mode ZIP, l'e-mail unique du lot inclut le tableau complet des tâches avec toutes les URL et leurs statuts.
Comportement par défaut : Si vous n'incluez pas notification_email dans votre requête, l'e-mail de fin est envoyé automatiquement à l'adresse e-mail du propriétaire du projet. Pour supprimer entièrement les notifications par e-mail, ce comportement par défaut ne peut actuellement pas être désactivé.
--- ## Rappels webhook Incluez le paramètre `callback_url` dans votre requête pour recevoir un POST webhook lorsque la tâche se termine. Nécessite un forfait avec accès aux webhooks. ### Exemple ```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" }' ``` ### Réponse (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Charge utile du rappel en mode URL unique / individuel En mode individuel, un **POST séparé est envoyé pour chaque URL** au fur et à mesure qu'elle se termine : ```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 } ``` Pour une conversion échouée : ```json { "job_id": "12345", "status": "failed", "batch_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Charge utile du rappel en mode ZIP En mode ZIP, un **seul POST est envoyé lorsque le lot entier se termine** : ```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"} ] } ```
Comportement des notifications, individuel vs ZIP : En mode individuel, vous recevez N POST webhook séparés (un par URL) et N e-mails séparés. En mode ZIP, vous recevez un seul POST webhook et un seul e-mail pour le lot entier. Concevez votre gestionnaire de webhook en conséquence.
--- ## Utiliser plusieurs méthodes de notification ensemble Vous pouvez combiner l'interrogation, l'e-mail et le webhook dans la même requête. Les trois fonctionnent indépendamment. ```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" }' ``` Après l'envoi, vous pouvez : 1. **Interroger** `GET /v1/convert/batch/{batch_id}` pour suivre la progression en temps réel 2. **Recevoir un POST webhook** à votre URL de rappel lorsque chaque conversion se termine 3. **Recevoir un e-mail** à l'adresse spécifiée lorsque chaque conversion se termine --- ## Paramètres de notification | Paramètre | Type | Obligatoire | Par défaut | Description | Restriction par forfait | |-----------|------|----------|---------|-------------|-------------| | `notification_email` | `string` | Non | E-mail du propriétaire du projet | Adresse e-mail pour recevoir les notifications de fin de tâche. | -- | | `callback_url` | `string` | Non | -- | URL pour recevoir un POST webhook à la fin. | Nécessite l'accès aux webhooks | --- ## Exigences de livraison des webhooks | Exigence | Détail | |-------------|--------| | **Méthode** | EnConvert envoie une requête `POST` avec `Content-Type: application/json`. | | **Délai** | Votre endpoint doit répondre dans un délai de **30 secondes**. | | **Codes de succès** | HTTP `200`, `201`, `202`, ou `204` sont considérés comme une livraison réussie. | | **Nouvelles tentatives** | Aucune nouvelle tentative en cas d'échec. Si la livraison du webhook échoue (réponse d'échec ou délai dépassé), les résultats restent disponibles via l'interrogation du statut du lot. | | **Authentification** | Aucun en-tête d'authentification n'est envoyé. Validez le `batch_id` par rapport à vos propres enregistrements si nécessaire. | --- ## Restrictions selon le forfait d'abonnement | Fonctionnalité | Founding | Indie | Studio | Enterprise | |---------|------|---------|-----|------------| | Mode asynchrone | Non | Oui | Oui | Oui | | Interrogation du statut du lot | Non | Oui | Oui | Oui | | Notifications par e-mail | Non | Oui | Oui | Oui | | Rappels webhook (`callback_url`) | Non | Non | Oui | Oui |
Remarque : Les notifications par e-mail ne sont pas soumises à une restriction de fonctionnalité distincte -- elles sont disponibles pour tout utilisateur de clé API privée ayant accès à l'asynchrone. Le paramètre notification_email ne nécessite aucune fonctionnalité de forfait spécifique. Les rappels webhook (callback_url) nécessitent la fonctionnalité has_webhook, disponible à partir des forfaits Studio.
--- ## Tester les webhooks Pendant le développement, utilisez [webhook.site](https://webhook.site) pour générer une URL de rappel temporaire à des fins de 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" }' ``` Consultez votre tableau de bord webhook.site pour inspecter la charge utile exacte du rappel une fois la tâche terminée. ## Questions fréquentes ### Comment recevoir un rappel webhook lorsqu'une tâche de conversion de fichier se termine ? Incluez le paramètre `callback_url` dans votre requête avec une clé API privée. EnConvert envoie un `POST` avec `Content-Type: application/json` à cette URL lorsque la tâche se termine. Les rappels webhook nécessitent un forfait avec accès aux webhooks (Studio, Production ou Enterprise). ### EnConvert relance-t-il les livraisons de webhook échouées ? Non. Votre endpoint doit répondre dans un délai de 30 secondes avec HTTP `200`, `201`, `202`, ou `204`. Si la livraison échoue, les résultats restent disponibles via l'interrogation du statut du lot à `GET /v1/convert/batch/{batch_id}`. ### Puis-je utiliser ensemble les notifications par e-mail, webhook et interrogation ? Oui. `notification_email`, `callback_url` et l'interrogation du statut fonctionnent tous indépendamment et peuvent être combinés dans la même requête. Si `notification_email` est omis, l'e-mail de fin est envoyé par défaut à l'adresse e-mail du propriétaire du projet. ### Pourquoi est-ce que je reçois un webhook par URL au lieu d'un seul pour tout le lot ? En mode individuel, vous recevez N POST webhook séparés (un par URL) et N e-mails séparés. Pour recevoir un seul webhook et un seul e-mail pour le lot entier, utilisez le mode ZIP, qui envoie un seul POST avec `total_tasks`, `successful_tasks`, `failed_tasks`, et un tableau `tasks`. ### Comment puis-je tester les rappels webhook pendant le développement ? Utilisez webhook.site pour générer une URL temporaire et transmettez-la comme `callback_url` dans votre requête. Le tableau de bord webhook.site affiche la charge utile JSON exacte qu'EnConvert livre lorsque la tâche se termine.