AuraDoc
AnmeldenKonto

Blog

Webhooks und REST-API in AuraDoc

Verbinden Sie AuraDoc mit Ihren Systemen: API-Schlüssel mit Bereichen, signierte Webhooks, Zustellprotokoll und automatische Wiederholungen.


Früher oder später möchte jedes Team, dass die Dokumente mit der übrigen Software sprechen: eine Datei per Skript hochladen, einen Workflow aus einem Planer starten oder sofort erfahren, wenn ein Dokument fertig verarbeitet ist. AuraDoc bietet dafür zwei sich ergänzende Wege. Über die REST-API bitten Ihre Systeme AuraDoc um etwas, über Webhooks meldet AuraDoc Ihren Systemen, dass etwas passiert ist. Dieser Beitrag behandelt beides und die Sicherheitsdetails, die im Produktivbetrieb zählen.

API-Schlüssel und Bereiche

Alles beginnt mit einem API-Schlüssel. Legen Sie unter Dashboard › Settings › API keys einen an, vergeben Sie einen Namen und wählen Sie die Bereiche. Bereiche begrenzen, was der Schlüssel darf; ein Schlüssel nur zum Hochladen braucht keine Rechte zur Verwaltung anderer Dinge. Ein Schlüssel kann keinen anderen mit größeren Bereichen erzeugen, und die wirksamen Berechtigungen sind stets die, die Schlüssel und Rolle der Person gemeinsam haben, wie in Teamrollen und Berechtigungen beschrieben. Anfragen tragen den Schlüssel im Authorization-Header als Bearer-Token.

Dieselbe Seite zeigt Nutzungsstatistiken je Schlüssel, damit Sie sehen, welche Integration aktiv ist und welche verstummt ist. In bezahlten Tarifen lässt sich außerdem ein Ratenlimit für einen einzelnen Schlüssel setzen, nützlich, wenn ein lautes Skript die anderen nicht ausbremsen soll. Wird ein Schlüssel öffentlich, löschen Sie ihn und erstellen einen neuen; auf Seiten von AuraDoc ändert sich sonst nichts.

Was die API kann

Die Integrationsseite der Dokumentation nennt die Basisadresse und enthält kopierfertige Beispiele. Heute können Sie ein Dokument hochladen, AuraDoc ein Dokument von einer URL einlesen lassen, einen Workflow-Lauf starten und eine Signaturanfrage erstellen, jeweils mit einer einzigen authentifizierten Anfrage. Es sind dieselben Vorgänge wie im Dashboard, ein per API erzeugtes Ergebnis erscheint daher wie jedes andere in der Oberfläche.

Wer lieber abfragt, statt Aufrufe zu empfangen, nutzt die Trigger-Endpunkte: Sie liefern neue Dokumente, abgeschlossene Workflow-Läufe und abgeschlossene Signaturen, dazu gibt es einen beschreibenden Katalog. Werkzeuge ohne Webhook-Empfang, etwa Tabellen-Add-ons oder No-Code-Plattformen, können sie regelmäßig abfragen. Die vollständige Referenz steht auf der Dokumentationsseite zu Integrationen.

Ausgehende Webhooks

Für Benachrichtigungen in Echtzeit öffnen Sie Dashboard › Webhooks und fügen einen Endpunkt hinzu. Die gewünschten Ereignisse wählen Sie aus einer Liste, darunter Dokument erstellt, klassifiziert und gelöscht, OCR und Übersetzung abgeschlossen oder fehlgeschlagen, Workflow-Ereignisse, Warnungen zum Speicherkontingent und Signaturereignisse. Beim Speichern zeigt AuraDoc das Signaturgeheimnis genau einmal an. Kopieren Sie es sofort in Ihren Empfangsdienst; geht es verloren, rotieren Sie das Geheimnis, ein neues wird erzeugt, und die Rotation steht im Audit-Protokoll.

Die Nutzlast lässt sich mit einer Vorlage von bis zu einigen tausend Zeichen formen und vor dem Speichern prüfen. Eine Testschaltfläche sendet ein Beispielereignis mit Test-Header, damit Sie prüfen können, ob Ihr Endpunkt erreichbar ist und den Body liest, bevor Sie sich darauf verlassen. Jeder Webhook lässt sich abschalten, ohne ihn zu löschen, was bei Wartungsfenstern hilft.

Signaturen prüfen und Ausfälle behandeln

Jede Zustellung ist signiert. AuraDoc berechnet mit Ihrem Geheimnis einen HMAC-SHA256 über Zeitstempel und Roh-Body und sendet das Ergebnis im Signatur-Header, dazu Header für Ereignisname, Webhook-ID, Zustell-ID, Zeitstempel und Wiederholungszähler. Ihr Empfänger sollte die Signatur aus dem Roh-Body neu berechnen, in konstanter Zeit vergleichen und Anfragen mit zu altem Zeitstempel ablehnen. So kann niemand ein Ereignis an Ihren Endpunkt fälschen, selbst wenn er die Adresse kennt.

Endpunkte fallen aus, und AuraDoc plant das ein. Schlägt eine Zustellung fehl, wird sie automatisch mit wachsenden Abständen wiederholt, von fünf Minuten bis zu sechs Stunden. Die Zustellansicht zeigt jeden Versuch mit Ergebnis, und nach der Fehlerbehebung können Sie manuell erneut auslösen. Da bei Wiederholungen dieselbe Zustell-ID verwendet wird, kann Ihr Empfänger Duplikate gefahrlos ignorieren. Wie Sie Webhooks mit Dateien von Speicheranbietern verbinden, lesen Sie unter Cloud-Speicher und überwachte Ordner.

Zurück zum Blog