Webhooks für Echtzeit-Sign.Plus Updates einrichten

Mit Webhooks können Sie Echtzeit-Updates über den Status Ihrer Umschläge im Sign.Plus erhalten. Dieser Artikel führt Sie durch den Prozess der Einrichtung und Handhabung von Webhooks für Ihre Sign.Plus-Integration.

Schritt 1: Erstellen Sie einen Webhook

Um Echtzeit-Updates zu erhalten, müssen Sie zuerst einen Webhook in der Sign.Plus erstellen. Hier ist wie:

1. Entscheiden Sie sich für eine Ziel-URL, bei der Sie Webhook Benachrichtigungen erhalten möchten. Dies sollte ein Endpunkt auf Ihrem Server sein, der so eingerichtet ist, dass eingehende POST-Anfragen bearbeitet werden.
2. Wählen Sie das Ereignis, das Sie verfolgen möchten. Sign.Plus bietet folgende Webhook Events an:
   • Umschlag_erledigt - Wenn ein Umschlag abgeschlossen ist
   • umvelope_abgelaufen - Wenn ein Umschlag abgelaufen ist
   • envelope_declined - When an envelope is declined
   • umvelope_voided - Wenn ein Umschlag storniert wird
3. Verwenden Sie die Sign.Plus API, um den Webhook zu erstellen. Sie müssen Ihre Ziel-URL und die Ereignisse, die Sie verfolgen möchten, angeben.

For detailed information on how to create a webhook using the Sign.Plus API, refer to the Create a webhook endpoint documentation.

Schritt 2: Webhook notfications bearbeiten

Sobald Sie Ihren Webhook eingerichtet haben, sendet Sign.Plus POST-Anfragen an Ihre angegebene URL, wann immer die aufgezeichneten Ereignisse auftreten. Hier ist, was du über die Handhabung dieser Benachrichtigungen wissen musst:

1. Anfragemethode: Alle Webhook-Benachrichtigungen werden als HTTP POST Anfragen gesendet.
2. Payload Structure: Der Webhook Payload ist ein JSON-Objekt, das zwei Hauptbereiche enthält:
   • Hook: Enthält Metadaten über den Webhook selbst.
   • Daten: Enthält Informationen über den Umschlag, der das Ereignis ausgelöst hat.
3. Payload Examples: Here are examples of payloads for different events:
   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Behandlung der Benachrichtigung: Wenn Ihr Server eine Webhook-Benachrichtigung erhält:
   • Überprüfen Sie die Payload um sicherzustellen, dass es eine gültige webhook Benachrichtigung ist.
   • Extrahieren Sie die relevanten Informationen aus der Payload.
   • Führen Sie alle notwendigen Aktionen basierend auf dem Ereignistyp aus (z.B. aktualisieren Sie Ihre Datenbank, benachrichtigen Sie Benutzer, lösen andere Prozesse aus).
   • Senden Sie eine200 OKAntwort, um den Empfang des Webhook zu bestätigen.

Best Practices

1. Sicherheit: Stellen Sie sicher, dass Ihr Webhook Endpunkt sicher ist. Erwägen Sie die Implementierung der Authentifizierung für Ihre Webhook URL.
2. Idempotenz: Gestalten Sie Ihren Webhook-Handler zu einer Epidemie. Das bedeutet, dass es das gleiche Ergebnis produzieren sollte, auch wenn der gleiche Webhook mehrfach empfangen wird.
3. Error Handling: Implementierung robuste Fehlerbehandlung in Ihrer Webhook Verarbeitungslogik.

Indem du dieser Anleitung folgst, kannst du Webhooks effektiv einrichten und handhaben damit Ihre Anwendung Echtzeit-Updates über Umschlagstatus im Sign erhalten kann. lus.