📖 Inhaltsverzeichnis
Was sind API- & Webhook-Protokolle?
API- und Webhook-Protokolle funktionieren wie ein technisches Aktivitätslogbuch. Sie protokollieren den Datenaustausch zwischen Ihrem System und Yousign, wozu das Folgende gehört:
an Yousign gesendete API-Aufrufe
von Yousign an Ihr System gesendete Webhooks
Details zu Anfrage und Antwort
Status jedes Ereignisses (Erfolg oder Fehler)
Die Protokolle sind für Entwickler:innen unerlässlich, um:
Fehler zu untersuchen
unerwartetes Verhalten zu verstehen
Integrationen unabhängiger zu debuggen
Wie greife ich auf API- & Webhook-Protokolle zu?
Sie können auf zwei Arten auf die Protokolle zugreifen:
Über das Hauptmenü
Klicken Sie in der linken Seitenleiste auf Entwickler:innen.
Hier haben Sie Zugriff auf API-Schlüssel und Webhooks.
Direkt aus einer Signaturanfrage
Wenn Sie eine bestimmte Signaturanfrage untersuchen:
Öffnen Sie die Detailseite der Signaturanfrage.
Klicken Sie auf das Drei-Punkte-Menü (…).
Folgende Optionen werden Ihnen angezeigt:
API-Aufrufprotokolle anzeigen
Webhook-Protokolle anzeigen
Webhooks anzeigen
Sie werden auf die Protokollseite weitergeleitet, auf der automatisch ein Filter für diese Signaturanfrage angewendet wird. Das spart enorm Zeit bei der Fehlerbehebung.
Protokollaufbewahrung verstehen (nach Lizenz)
Die Protokolle werden je nach Lizenz für eine begrenzte Zeit gespeichert:
Lizenz | Aufbewahrungsdauer der Protokolle |
Plus | 1 Tag |
Pro | 7 Tage |
Scale | 30 Tage |
API-Testversion | 7 Tage |
Nach Ablauf dieser Frist werden die Protokolle endgültig gelöscht und können nicht mehr aufgerufen werden.
Wenn Sie Probleme regelmäßig erst mehrere Tage nach ihrem Auftreten untersuchen, kann die Aufbewahrungsfrist Ihrer Protokolle Ihre Fähigkeit zur Fehlerbehebung beeinträchtigen.
Protokolle effizient durchsuchen und filtern
Die Protokollseite kann eine große Anzahl von Ereignissen enthalten. Filter helfen Ihnen dabei, das gesuchte Ereignis schnell zu finden.
Oben auf der Seite können Sie zwischen den folgenden Ansichten wählen:
API-Aufrufe
Gesendete Webhooks
Nutzen Sie dann die Filter, um Ihre Suche einzugrenzen. Hiernach können Sie filtern:
🔎 Signaturanfrage-ID
Suchen Sie nach Protokollen, die mit einer bestimmten Signaturanfrage-ID verknüpft sind. Das ist besonders nützlich, wenn jede Sekunde zahlreiche Protokolle generiert werden.
⏱ Datumsbereich
Filtern Sie in einem genauen Datumsbereich und nicht nur an einem bestimmten Datum nach Protokollen.
Dadurch wird es viel einfacher, ein Ereignis zu finden, das zu einem bestimmten Zeitpunkt stattgefunden hat.
📌 Status
Filtern Sie nach Status, um schnell fehlgeschlagene oder erfolgreiche Aufrufe zu identifizieren.
🔑 API-Schlüssel (nur API-Protokolle)
Wenn Sie mehrere API-Schlüssel verwenden, können Sie die Protokolle nach API-Schlüssel filtern. So sehen Sie nur Aufrufe mit einem bestimmten API-Schlüssel.
Klicken Sie auf „Anwenden“, um Ihre Filter zu aktivieren.
Was wird in den Protokollen aufgezeichnet?
Die Protokolle liefern detaillierte technische Informationen, darunter:
alle API-Aufrufe, einschließlich GET-Anfragen (z. B. das Abrufen von Signaturanfragen oder Unterzeichnerinformationen)
Webhook-Ereignisse, die von Yousign gesendet werden
Anfrage- und Antwortbodies
Anfragen und Antworten, die multipart/form-data verwenden (zum Beispiel beim Hochladen von Dokumenten) werden ebenfalls aufbewahrt, damit Sie den gesamten technischen Austausch einsehen können.
Protokolldetails ansehen
So sehen Sie alle Details:
Klicken Sie in der Liste auf einen API-Aufruf oder einen Webhook.
Es öffnet sich eine Seitenleiste mit den technischen Details.
Sie können diese Leiste auf eine ganze Seite erweitern, um die Lesbarkeit bei der Überprüfung komplexer Nutzlasten zu verbessern.
Sie brauchen Hilfe bei der Untersuchung eines Problems?
Falls die Protokolle nicht eindeutig erklären, was passiert ist, kann Ihnen unser Team bei weiteren Untersuchungen helfen.
Sie können uns direkt über die Web-App kontaktieren:
Klicken Sie auf der linken Seite des Bildschirms auf Hilfe (direkt über den Einstellungen).
Wählen Sie „Feedback teilen“ oder „Kontaktieren Sie uns“.
Diese Infos sollten Sie angeben, damit wir das Problem schneller analysieren können:
Signaturanfrage-ID (falls relevant)
ungefähres Datum und ungefähre Uhrzeit des Problems
ob der API-Aufruf oder der Webhook einen Fehler- oder Erfolgsstatus anzeigt
alle relevanten Fehlermeldungen, die in den Protokollen sichtbar sind
Die Bereitstellung dieser technischen Details ermöglicht unserem Team eine effizientere Untersuchung.