--- seo_title: Webhook-Callbacks & Job-Benachrichtigungen | EnConvert meta_desc: Erhält einen Webhook-POST via callback_url, sobald asynchrone Konvertierungsjobs abgeschlossen sind. Dazu E-Mail und Polling über GET /v1/convert/batch/{batch_id}. keywords: webhook callback api konvertierung, webhook bei abgeschlossenem konvertierungsjob, callback_url parameter verwenden, batch status abfragen api, e-mail benachrichtigung nach konvertierung, webhook payload json beispiel, webhook callback testen api, asynchrone jobs benachrichtigung api --- # Webhook-Callbacks & Job-Benachrichtigungen für Konvertierungen EnConvert benachrichtigt dich über drei unabhängige Mechanismen, wenn asynchrone und Batch-Konvertierungsjobs abgeschlossen sind: Polling von `GET /v1/convert/batch/{batch_id}`, Webhook-Callbacks über den Parameter `callback_url` und E-Mail-Benachrichtigungen über `notification_email`. Alle drei lassen sich in einer einzigen Anfrage kombinieren, und fertige Dateien werden über Download-URLs in der Batch-Status-Antwort abgerufen. Diese Seite dokumentiert die Callback-Payloads, Zustellanforderungen und Plan-Beschränkungen für jede Methode.
Nur private Schlüssel: Job-Benachrichtigungen und Batch-Status-Polling sind nur verfügbar, wenn du dich mit einem privaten API-Schlüssel (X-API-Key: sk_...) authentifizierst. Öffentliche Schlüssel unterstützen weder async noch Batch-Verarbeitung.
--- ## Überblick | Methode | Parameter / Endpunkt | Beschreibung | |--------|---------------------|-------------| | Polling | `GET /v1/convert/batch/{batch_id}` | Fragt Echtzeit-Status, Fortschrittszahlen und Download-URLs ab. | | E-Mail | `notification_email` | Sendet eine Abschluss-E-Mail mit Job-Status und einem Dashboard-Link. | | Webhook | `callback_url` | Sendet eine POST-Anfrage mit den Job-Ergebnissen an deinen Server. | Alle drei Methoden funktionieren sowohl für asynchrone Einzel-URL-Jobs als auch für Multi-URL-Batch-Jobs über die Endpunkte [url-to-pdf](/de/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/de/docs/endpoints/convert/web-pages/url-to-screenshot.md), [website-to-pdf](/de/docs/endpoints/convert/web-pages/website-to-pdf.md) und [website-to-screenshot](/de/docs/endpoints/convert/web-pages/website-to-screenshot.md). --- ## Batch-Status-Polling Die empfohlene Methode, um den Job-Fortschritt zu verfolgen. Frage den Batch-Status-Endpunkt mit der `batch_id` ab, die in der initialen 202-Antwort zurückgegeben wurde. ``` GET /v1/convert/batch/{batch_id} X-API-Key: sk_your_private_key ``` ### Antwort ```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 } ] } ``` ### Statuswerte | Status | Bedeutung | |--------|---------| | `processing` | Mindestens eine URL wird noch konvertiert. | | `completed` | Alle URLs wurden erfolgreich konvertiert. | | `partial` | Alle URLs sind fertig, aber einige sind fehlgeschlagen. | | `failed` | Alle URLs sind fehlgeschlagen. | Im ZIP-Modus (`output_mode: "zip"`) wird bei Abschluss eine `zip_download_url` für das gesamte Archiv bereitgestellt. Im Individual-Modus hat jedes Item seine eigene `download_url`. Vollständige Details zum Antwortschema findest du unter [Batch-Verarbeitung](/de/docs/guides/batch-processing.md#batch-status-polling). --- ## E-Mail-Benachrichtigungen Füge den Parameter `notification_email` zu deiner Anfrage hinzu, um eine E-Mail zu erhalten, sobald der Job abgeschlossen ist. Wenn du diesen Parameter weglässt, wird die E-Mail standardmäßig an die **E-Mail-Adresse des Projektinhabers** gesendet. ### Beispiel ```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" }' ``` ### Antwort (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### E-Mail-Inhalt Die Abschluss-E-Mail enthält: - **Status-Header** mit einem farbigen Banner (grün bei Erfolg, rot bei Fehlschlag) - **Job-ID** und **Batch-ID** (falls Teil eines Batches) - **Statustext** (Erfolg oder fehlgeschlagen) - **Statischer Text**, der Nutzer anweist, Dateien über ihr Dashboard herunterzuladen - **Tasks-Tabelle** (nur bei ZIP-Modus-Batch-Jobs) mit den Spalten: #, URL (gekürzt auf 50 Zeichen), Status und Ausgabedateiname Im Individual-Modus (einschließlich Multi-URL-Individual-Batches) enthält jede URL-bezogene E-Mail nur die Job-ID und den Status -- keine Tasks-Tabelle. Im ZIP-Modus enthält die einzelne Batch-E-Mail die vollständige Tasks-Tabelle mit allen URLs und deren Status.
Standardverhalten: Wenn du notification_email nicht in deiner Anfrage angibst, wird die Abschluss-E-Mail automatisch an die E-Mail-Adresse des Projektinhabers gesendet. Dieses Standardverhalten kann derzeit nicht deaktiviert werden, um E-Mail-Benachrichtigungen vollständig zu unterdrücken.
--- ## Webhook-Callbacks Füge den Parameter `callback_url` zu deiner Anfrage hinzu, um bei Abschluss des Jobs einen Webhook-POST zu erhalten. Erfordert einen Plan mit Webhook-Zugriff. ### Beispiel ```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" }' ``` ### Antwort (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Callback-Payload für Einzel-URL / Individual-Modus Im Individual-Modus wird **für jede URL bei Abschluss ein separater POST gesendet**: ```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 } ``` Bei einer fehlgeschlagenen Konvertierung: ```json { "job_id": "12345", "status": "failed", "batch_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Callback-Payload für ZIP-Modus Im ZIP-Modus wird **ein einzelner POST gesendet, wenn der gesamte Batch abgeschlossen ist**: ```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"} ] } ```
Individual- vs. ZIP-Benachrichtigungsverhalten: Im Individual-Modus erhältst du N separate Webhook-POSTs (einen pro URL) und N separate E-Mails. Im ZIP-Modus erhältst du einen Webhook-POST und eine E-Mail für den gesamten Batch. Gestalte deinen Webhook-Handler entsprechend.
--- ## Mehrere Benachrichtigungsmethoden gemeinsam nutzen Du kannst Polling, E-Mail und Webhook in derselben Anfrage kombinieren. Alle drei funktionieren unabhängig voneinander. ```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" }' ``` Nach dem Absenden kannst du: 1. **Abfragen** von `GET /v1/convert/batch/{batch_id}` für Echtzeit-Fortschritt 2. **Einen Webhook-POST erhalten** an deiner Callback-URL, sobald jede Konvertierung abgeschlossen ist 3. **Eine E-Mail erhalten** an der angegebenen Adresse, sobald jede Konvertierung abgeschlossen ist --- ## Benachrichtigungsparameter | Parameter | Typ | Erforderlich | Standard | Beschreibung | Plan-Beschränkung | |-----------|------|----------|---------|-------------|-------------| | `notification_email` | `string` | Nein | E-Mail des Projektinhabers | E-Mail-Adresse für Job-Abschluss-Benachrichtigungen. | -- | | `callback_url` | `string` | Nein | -- | URL, die bei Abschluss einen Webhook-POST erhält. | Erfordert Webhook-Zugriff | --- ## Anforderungen an die Webhook-Zustellung | Anforderung | Detail | |-------------|--------| | **Methode** | EnConvert sendet eine `POST`-Anfrage mit `Content-Type: application/json`. | | **Timeout** | Dein Endpunkt muss innerhalb von **30 Sekunden** antworten. | | **Erfolgscodes** | HTTP `200`, `201`, `202` oder `204` gelten als erfolgreiche Zustellung. | | **Wiederholungen** | Keine Wiederholungen bei Fehlschlag. Wenn die Webhook-Zustellung fehlschlägt (keine Erfolgsantwort oder Timeout), bleiben die Ergebnisse weiterhin über Batch-Status-Polling verfügbar. | | **Authentifizierung** | Es werden keine Authentifizierungs-Header gesendet. Prüfe bei Bedarf die `batch_id` gegen deine eigenen Aufzeichnungen. | --- ## Plan-Beschränkungen nach Abonnement | Funktion | Founding | Indie | Studio | Enterprise | |---------|------|---------|-----|------------| | Async-Modus | Nein | Ja | Ja | Ja | | Batch-Status-Polling | Nein | Ja | Ja | Ja | | E-Mail-Benachrichtigungen | Nein | Ja | Ja | Ja | | Webhook-Callbacks (`callback_url`) | Nein | Nein | Ja | Ja |
Hinweis: E-Mail-Benachrichtigungen sind nicht separat feature-beschränkt -- sie stehen jedem privaten API-Schlüssel-Nutzer mit Async-Zugriff zur Verfügung. Der Parameter notification_email erfordert kein bestimmtes Plan-Feature. Webhook-Callbacks (callback_url) erfordern das Feature has_webhook, das ab dem Studio-Plan verfügbar ist.
--- ## Webhooks testen Verwende während der Entwicklung [webhook.site](https://webhook.site), um eine temporäre Callback-URL zum Testen zu generieren: ```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" }' ``` Besuche dein webhook.site-Dashboard, um die exakte Callback-Payload zu untersuchen, sobald der Job abgeschlossen ist. ## Häufig gestellte Fragen ### Wie erhalte ich einen Webhook-Callback, wenn ein Dateikonvertierungsjob abgeschlossen ist? Füge den Parameter `callback_url` zusammen mit einem privaten API-Schlüssel zu deiner Anfrage hinzu. EnConvert sendet einen `POST` mit `Content-Type: application/json` an diese URL, sobald der Job abgeschlossen ist. Webhook-Callbacks erfordern einen Plan mit Webhook-Zugriff (Studio, Production oder Enterprise). ### Wiederholt EnConvert fehlgeschlagene Webhook-Zustellungen? Nein. Dein Endpunkt muss innerhalb von 30 Sekunden mit HTTP `200`, `201`, `202` oder `204` antworten. Schlägt die Zustellung fehl, bleiben die Ergebnisse weiterhin über Batch-Status-Polling unter `GET /v1/convert/batch/{batch_id}` verfügbar. ### Kann ich E-Mail-, Webhook- und Polling-Benachrichtigungen zusammen verwenden? Ja. `notification_email`, `callback_url` und Status-Polling funktionieren alle unabhängig voneinander und lassen sich in derselben Anfrage kombinieren. Wird `notification_email` weggelassen, geht die Abschluss-E-Mail standardmäßig an die E-Mail-Adresse des Projektinhabers. ### Warum erhalte ich einen Webhook pro URL statt eines für den gesamten Batch? Im Individual-Modus erhältst du N separate Webhook-POSTs (einen pro URL) und N separate E-Mails. Um einen einzelnen Webhook und eine einzelne E-Mail für den gesamten Batch zu erhalten, verwende den ZIP-Modus, der einen POST mit `total_tasks`, `successful_tasks`, `failed_tasks` und einem `tasks`-Array sendet. ### Wie kann ich Webhook-Callbacks während der Entwicklung testen? Verwende webhook.site, um eine temporäre URL zu generieren, und übergib sie als `callback_url` in deiner Anfrage. Das webhook.site-Dashboard zeigt die exakte JSON-Payload, die EnConvert bei Abschluss des Jobs liefert.