Webhooks
Erhalte eine signierte Nachricht, sobald ein Lauf fertig ist, und frage nicht mehr ständig nach der Datei
Ein Webhook ist eine Adresse von dir, die DocTransform jedes Mal aufruft, wenn einer deiner Läufe fertig ist. Denk an eine Türklingel: Statt immer wieder zu fragen, ob der Lauf fertig ist, wartest du, und DocTransform klingelt, sobald er es ist. Das Klingeln ist eine kurze Nachricht, ein Ereignis. Es sagt dir, welcher Lauf fertig ist, und gibt dir einen Link zur Datei.
Einen Webhook einrichten
Du brauchst nur eines: eine Adresse, die mit https:// beginnt und aus dem Internet erreichbar ist. Ein Werkzeug wie Zapier gibt dir eine, dein eigener Server auch.
Öffne die Karte Webhooks
Gehe auf deine Kontoseite und suche die Karte Webhooks. Klicke auf Webhook hinzufügen.
Füge deine Adresse ein
Füge sie bei Adresse, an die Ereignisse gehen ein. Ein Lauf ist fertig und Ein Lauf ist fehlgeschlagen sind schon angehakt, ebenso Für alle Vorlagen. Ändere das nur, wenn du es brauchst.
Speichern und testen
Klicke auf Webhook speichern, dann auf Testereignis senden. Die Antwort erscheint im Zustellprotokoll auf demselben Bildschirm, so weißt du vor einem echten Lauf, dass es klappt.
Signaturgeheimnis kopieren
Nur wenn dein eigener Code die Ereignisse prüft: Klicke unter Signaturgeheimnis auf Anzeigen, dann auf Kopieren. Wer Zapier, Make oder n8n nutzt, kann das überspringen.
Du kannst bis zu 5 Webhooks anlegen, in jedem Tarif gleich. Webhooks verwaltest du nur auf der Kontoseite, nicht über die API. Zustellungen zählen nie auf dein Kontingent.
GET /runs/{id} funktioniert weiter und bleibt bestehen. Du schreibst Code? Lies Webhooks prüfen. Du nutztZapier, Make oder n8n? Dann brauchst du nur die Adresse, die diese Werkzeuge dir geben.Was ankommt
Jedes Ereignis ist ein POST mit einem JSON-Inhalt aus drei Teilen: type, timestamp (wann der Lauf fertig wurde) und data. Jeder Schlüssel ist immer da und ist null, wenn er nicht zutrifft, damit ein Werkzeug jedes Mal dieselben Felder zuordnet. Nie enthalten sind Dateiinhalt, Spalten, Dateinamen oder Vorlagennamen: Details liefert GET /runs/{id}.
run.succeeded kommt, wenn die Datei bereit ist:
{
"type": "run.succeeded",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-30T10:15:00Z",
"error": null
}
}run.failed kommt, wenn ein Lauf ohne Datei endet. Es gibt keinen Link, und error.code ist einer der Fehlercodes:
{
"type": "run.failed",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "failed",
"download_url": null,
"expires_at": null,
"error": {
"code": "PIPELINE_FAILED",
"message": "The pipeline failed while running the Template."
}
}
}webhook.test sendet Testereignis senden. Sein Link funktioniert nicht, ignoriere es also mit if type == "webhook.test":
{
"type": "webhook.test",
"timestamp": "2026-09-27T10:15:00+00:00",
"data": {
"run_id": "run_test",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-28T10:15:00+00:00",
"error": null
}
}Prüfen, ob ein Ereignis echt ist
Wer deine Adresse herausfindet, könnte ihr etwas schicken. Jedes Ereignis trägt eine Signatur, die nur DocTransform und du erzeugen können, so erkennt dein Code ein echtes von einem falschen. Webhooks prüfen zeigt, wie, mit Beispielen zum Kopieren.
Wiederholungen und Ausschalten
Ein Ereignis gilt nur als zugestellt, wenn deine Adresse binnen 10 Sekunden mit einem 2xx-Status antwortet. Weiterleitungen werden nicht verfolgt. Alles andere wird erneut versucht, ein kurzer Ausfall bei dir verliert also nichts. Nach jedem fehlgeschlagenen Versuch wartet DocTransform länger:
| Nach fehlgeschlagenem Versuch | Wartezeit bis zum nächsten |
|---|---|
| 1 | 1 Min. |
| 2 | 5 Min. |
| 3 | 30 Min. |
| 4 | 2 Std. |
| 5 | 6 Std. |
| 6 | 12 Std. |
| 7 | 24 Std. |
| 8 | 18 Std. |
Das sind 9 Versuche über etwa 2,6 Tage (62 Std. 36 Min., plus oder minus 10 %). Dass ein bereits verarbeitetes Ereignis nochmals kommt, ist normal: siehe Wiederholungen und Duplikate stoppen.
Wenn Zustellungen fehlschlagen
Der Webhook bleibt eingeschaltet und zeigt, dass er fehlschlägt. Öffne sein Zustellprotokoll, um jeden Versuch und den Grund zu sehen. Nach 24 Stunden Fehlschlagen bekommst du eine E-Mail. Sobald deine Adresse wieder antwortet, stellt der nächste Versuch das Ereignis zu.
Das Zustellprotokoll nennt bei jedem fehlgeschlagenen Versuch einen dieser Gründe:
| Grund | In einfachen Worten | Was du tun kannst |
|---|---|---|
WEBHOOK_UNREACHABLE | Wir konnten deine Adresse nicht erreichen: Sie existiert nicht, ist offline oder hat uns abgewiesen. | Prüfe die Adresse auf Tippfehler und ob dein Empfänger läuft. |
WEBHOOK_TIMEOUT | Deine Adresse hat länger als 10 Sekunden zum Antworten gebraucht. | Antworte zuerst und erledige die langsame Arbeit danach. |
WEBHOOK_REJECTED | Deine Adresse hat geantwortet, aber mit einem Fehler statt eines 2xx-Status. | Sieh im Protokoll deines Empfängers nach, warum er abgelehnt hat. |
WEBHOOK_REDIRECTED | Deine Adresse hat uns an eine andere Adresse weitergeschickt, und dem folgen wir nie. | Füge stattdessen die endgültige Adresse ein. |
WEBHOOK_URL_BLOCKED | Die Adresse zeigt in ein privates Netzwerk, deshalb senden wir nicht mehr an sie. | Nimm eine öffentliche https-Adresse. Zum Ausprobieren auf dem eigenen Rechner siehe Webhooks lokal testen. |
WEBHOOK_SECRET_UNREADABLE | Wir konnten das Signaturgeheimnis des Webhooks nicht lesen, deshalb wurde nichts gesendet. | Öffne den Webhook und klicke auf Geheimnis ändern. |
WEBHOOK_DISABLED | Der Webhook war ausgeschaltet, deshalb wurde das Ereignis nicht gesendet. | Klicke auf Einschalten. |
Wenn ein Webhook ausgeschaltet wird
Nach 10 fehlgeschlagenen Versuchen in Folge, verteilt über mehr als 5 Tage, steht der Webhook auf Aus, und du bekommst eine zweite E-Mail. Es wird nichts mehr gesendet. Repariere deine Adresse und klicke auf Einschalten: Es bietet an, die Zustellungen nachzusenden, die beim Ausschalten gestoppt wurden, aus den letzten 3 Tagen. Ein Lauf, der endete, während der Webhook aus war, wird nicht gesendet. Hole seine Datei mit GET /runs/{id}/output oder über seinen Download-Link, solange er gilt. Du kannst auch bei einer einzelnen Zustellung auf Erneut senden klicken.
Wenn deine Adresse „weg“ meldet
Antwortet deine Adresse mit 410 Gone, wird der Webhook sofort ausgeschaltet, weil diese Antwort bedeutet, dass sie nie wiederkommt. Das passiert oft, wenn ein Zap oder Szenario gelöscht oder ausgeschaltet bleibt. Hole den Empfänger zurück und klicke auf Einschalten.
Die Datei herunterladen
download_url lädt die Datei ohne API-Schlüssel herunter, bis expires_at. Das sind 3 Tage nach dem Ende des Laufs, wenn ein Webhook den Lauf erhält, sonst 30 Minuten, genau wie bei GET /runs/{id}/output. Bei run.failed ist es null, ebenso bei einer Zustellung nach Ablauf der Datei, etwa einem späten Erneut senden. Ein abgelaufener Link antwortet DOWNLOAD_LINK_EXPIRED: Führe die Vorlage erneut aus.
Webhooks lokal testen
DocTransform sendet nur an öffentliche https-Adressen, localhost wird also abgelehnt. Ein Tunnel gibt deinem lokalen Server eine öffentliche Adresse. Dieser braucht kein Konto:
cloudflared tunnel --url http://localhost:8000Füge die ausgegebene Adresse plus deinen Pfad in einen Webhook ein und klicke dann auf Testereignis senden. ngrok leistet dasselbe. Lösche den Webhook danach, denn die Tunneladresse ändert sich jedes Mal.
Sehen, was passiert ist
API-Aktivität auf deiner Kontoseite listet jede Anfrage deiner API-Schlüssel der letzten 90 Tage, auch abgelehnte. Das Zustellprotokoll jedes Webhooks zeigt jeden Versuch mit seiner Antwort und einer Schaltfläche Erneut senden. Beide sind über die Lauf-ID verbunden: Klicke auf Diesen Lauf ansehen, um zu wechseln.