API Documentation

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, url-to-screenshot, website-to-pdf und website-to-screenshot.

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#

{
    "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.

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#

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": "[email protected]"
  }'

Antwort (HTTP 202 Accepted)#

{
    "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#

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)#

{
    "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:

{
    "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:

{
    "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:

{
    "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.

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": "[email protected]",
    "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, um eine temporäre Callback-URL zum Testen zu generieren:

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.

← File Ingestion Batch Processing →