DocuSeal: API, Webhooks und Automatisierung
Auf einen Blick
| Gilt für | DocuSeal 3.3.x selbst gehostet (Open Source); REST-API unter /api, Webhooks, MCP-Server; Bibliotheken für JavaScript, Python, PHP, Ruby, C#, Java und Go |
|---|---|
| Bereich | Server-Software |
| Dauer | erster API-Aufruf ca. 15 Minuten; Integration je nach System |
| Rechte | Administrator in DocuSeal; Entwickler- bzw. Admin-Zugang zum anzubindenden System |
| Stand | Oktober 2026 |
DocuSeal per API und Webhooks automatisieren bedeutet, Unterschriftsprozesse direkt aus anderen Systemen zu starten und ihre Ergebnisse zurückzuschreiben: Das Personalsystem verschickt den Arbeitsvertrag, das CRM den Kundenauftrag, und sobald alle unterschrieben haben, landet das PDF automatisch in der Akte. Die selbst gehostete Open-Source-Version enthält API und Webhooks ohne Aufpreis. Diese Anleitung zeigt Authentifizierung, die wichtigsten Endpunkte, den sicheren Empfang von Webhooks, Beispiele mit n8n und den MCP-Server für KI-Assistenten.
Überblick: Schnittstellen von DocuSeal
| Baustein | Zweck | Einstellung in DocuSeal |
|---|---|---|
| REST-API | Vorlagen und Einreichungen anlegen, abfragen, archivieren; Dokumente herunterladen | Einstellungen › API |
| Webhooks | DocuSeal meldet Ereignisse aktiv an eine URL | Einstellungen › Webhooks |
| MCP-Server | KI-Assistenten (z. B. Claude Desktop, VS Code) suchen Vorlagen und versenden Dokumente | Einstellungen › MCP |
| Eingebettetes Signieren und eingebetteter Editor | Formulare in eigene Webanwendungen einbauen | nur Pro |
Schritt 1: API-Schlüssel
- Einstellungen › API öffnen und den API-Schlüssel anzeigen bzw. kopieren.
- Den Schlüssel wie ein Administratorpasswort behandeln: Er hat alle Rechte des Kontos. Nur im Secret-Speicher der aufrufenden Anwendung ablegen, nie im Quellcode oder in Tickets.
- Bei Verdacht auf Missbrauch neu erzeugen.
Die Basisadresse der selbst gehosteten API ist https://sign.firma.de/api (statt https://api.docuseal.com in der Cloud-Dokumentation). Jeder Aufruf trägt den Header X-Auth-Token.
# Vorlagen auflisten
curl -s https://sign.firma.de/api/templates \
-H "X-Auth-Token: $DOCUSEAL_TOKEN"
Schritt 2: Dokument per API zur Unterschrift senden
curl -s -X POST https://sign.firma.de/api/submissions \
-H "X-Auth-Token: $DOCUSEAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_id": 12,
"send_email": true,
"order": "preserved",
"submitters": [
{ "role": "Mitarbeiter", "email": "max.muster@example.de", "name": "Max Muster",
"values": { "Personalnummer": "4711", "Eintrittsdatum": "2026-11-01" } },
{ "role": "Personalabteilung", "email": "personal@firma.de" }
]
}'
roleentspricht dem Namen der Partei in der Vorlage,valuesfüllt Felder anhand ihres Namens vor.- Mit
"send_email": falseverschickt DocuSeal keine Mail; die Antwort enthält dann die Unterschriftslinks (embed_src) zur eigenen Weitergabe. - Weitere wichtige Endpunkte:
| Endpunkt | Funktion |
|---|---|
GET /api/submissions, GET /api/submissions/{id} |
Einreichungen und Status abfragen |
GET /api/submissions/{id}/documents |
Links zu den signierten PDFs |
POST /api/submissions/pdf, /docx, /html |
Einreichung direkt aus einem Dokument ohne gespeicherte Vorlage |
POST /api/templates/pdf, /docx, /html |
Vorlage aus Dokument mit Feld-Tags erzeugen |
PUT /api/submitters/{id} |
Empfänger ändern, Felder vorbelegen, E-Mail erneut senden |
DELETE /api/submissions/{id} |
Einreichung archivieren |
- Offizielle Bibliotheken gibt es für JavaScript/TypeScript, Python, PHP, Ruby, C#, Java und Go. Die vollständige Beschreibung liegt als OpenAPI-Datei im Repository.
- Der Testmodus trennt Testvorlagen und -einreichungen vom Produktivbestand.
Schritt 3: Webhooks einrichten
- Einstellungen › Webhooks öffnen, Ziel-URL eintragen (nur HTTPS) und die gewünschten Ereignisse wählen.
- Ein Webhook-Geheimnis anlegen bzw. die HMAC-Signatur aktivieren.
- Mit Test eine Beispielnachricht senden und im Zielsystem prüfen.
| Ereignis | Auslöser |
|---|---|
form.viewed |
Empfänger öffnet das Formular zum ersten Mal |
form.started |
Empfänger beginnt mit dem Ausfüllen |
form.completed |
eine Partei hat fertig unterschrieben |
form.declined |
Empfänger lehnt ab |
submission.created, submission.completed, submission.expired, submission.archived |
Einreichung angelegt, von allen abgeschlossen, abgelaufen, archiviert |
template.created, template.updated, template.archived |
Änderungen an Vorlagen |
- Nicht beantwortete oder fehlerhafte Zustellungen (Status 4xx/5xx) wiederholt DocuSeal mehrfach innerhalb von 48 Stunden.
- Für den Abschluss eines Vorgangs mit mehreren Parteien
submission.completedverwenden;form.completedkommt je Partei.
Webhooks prüfen (HMAC)
DocuSeal sendet im Header X-Docuseal-Signature den Wert Zeitstempel.Signatur. Die Signatur ist ein HMAC-SHA256 über Zeitstempel + "." + Rohdaten des Body. Der Empfänger sollte Nachrichten verwerfen, deren Signatur nicht passt oder deren Zeitstempel mehr als fünf Minuten abweicht:
import hmac, hashlib, time
def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
ts, _, sig = header.partition(".")
if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)
Grundlagen: HMAC. Zusätzlich kann die Webhook-URL eigene Header (z. B. ein festes Token) verlangen.
Beispiel: Personalprozess mit n8n
- Auslöser: Im Personalsystem wird ein neuer Mitarbeiter angelegt → n8n erhält die Daten.
- HTTP-Request-Knoten ruft
POST /api/submissionsmit Vorlage, Partei-Rollen und vorbelegten Feldern auf. - Webhook-Knoten in n8n empfängt
submission.completed, prüft die Signatur und lädt über die Dokument-URLs das signierte PDF samt Prüfprotokoll. - Ablage in der digitalen Personalakte bzw. im DMS, Benachrichtigung an die Personalabteilung.
Gleiches funktioniert mit Make, Zapier oder eigenem Code. Arbeitsverträge mit Befristung brauchen trotzdem Schriftform, siehe DocuSeal: Elektronische Signatur – Rechtslage in Deutschland.
MCP-Server für KI-Assistenten
- Unter Einstellungen › MCP den MCP-Server aktivieren und ein Token erzeugen. DocuSeal zeigt die Konfiguration für den MCP-Client an.
- Der Assistent kann dann Vorlagen und Dokumente suchen, Vorlagen anlegen, Felder vorbelegen und Dokumente versenden.
- Vorsicht: Ein KI-Assistent mit Versandrechten verschickt rechtlich relevante Dokumente. Nur für ausgewählte Benutzer freigeben, Token getrennt halten und die Funktion deaktivieren, wenn sie nicht genutzt wird – beim Deaktivieren werden alle MCP-Verbindungen sofort beendet.
Hinweise
- Dokument-Links laufen ab: Die Download-Links der API gelten standardmäßig 40 Minuten (
FILE_URLS_EXPIRE_MINUTES). Dokumente sofort nach dem Webhook abholen. - Firewall: Webhooks gehen vom DocuSeal-Server aus. Ausgehende Verbindungen nur zu den bekannten Zielen erlauben.
- Fehlerbehandlung: Ereignisse können mehrfach ankommen – Empfänger idempotent bauen, z. B. über die ID der Einreichung.
- Bei Integration von DocuSeal in Fachanwendungen, Portale und Workflows unterstützt Sie die individuelle Softwareentwicklung von m.a.x. it.
Siehe auch
- DocuSeal – Überblick und alle Artikel der Reihe
- DocuSeal: Vorlagen erstellen und Dokumente zur Unterschrift senden
- DocuSeal: Absichern, Backup und Betrieb
- Webhook
Links und Quellen
Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung?
