Einrichten von Webhooks für Echtzeit-Updates in Sign.Plus

Mit Webhooks erhalten Sie Echtzeit-Updates zum Status von Envelopes in Sign.Plus. Dieser Artikel führt Sie durch den Prozess der Einrichtung und Verarbeitung von Webhooks für Ihre Sign.Plus-Integration.

Schritt 1: Webhook erstellen

Um Echtzeit-Updates zu erhalten, müssen Sie zunächst einen Webhook in Sign.Plus erstellen. So geht's:

1. Legen Sie eine Ziel-URL fest, an die Webhook-Benachrichtigungen gesendet werden sollen. Dabei sollte es sich um einen Endpunkt auf Ihrem Server handeln, der für die Verarbeitung eingehender POST-Anfragen eingerichtet ist.
2. Wählen Sie die Ereignisse aus, die Sie verfolgen möchten. Sign.Plus bietet folgende Webhook-Ereignisse:
   • envelope_completed

      - Wenn ein Envelope abgeschlossen wird

   • envelope_expired

      - Wenn ein Envelope abläuft

   • envelope_declined

      - Wenn ein Envelope abgelehnt wird

   • envelope_voided

      - Wenn ein Envelope annulliert wird

3. Verwenden Sie die Sign.Plus API, um den Webhook zu erstellen. Sie müssen Ihre Ziel-URL und die Ereignisse angeben, die Sie verfolgen möchten.

Ausführliche Informationen zur Erstellung eines Webhooks mit der Sign.Plus API finden Sie in der Dokumentation zum Endpunkt „Webhook erstellen“.

Schritt 2: Webhook-Benachrichtigungen verarbeiten

Sobald Sie Ihren Webhook eingerichtet haben, sendet Sign.Plus POST-Anfragen an die von Ihnen angegebene URL, sobald die verfolgten Ereignisse eintreten. Folgendes müssen Sie über die Verarbeitung dieser Benachrichtigungen wissen:

1. Anfragemethode: Alle Webhook-Benachrichtigungen werden als HTTP 

   POST

   -Anfragen gesendet.

2. Payload-Struktur: Die Webhook-Payload ist ein JSON-Objekt, das zwei Hauptabschnitte enthält:
   • hook

     : Enthält Metadaten zum Webhook selbst.

   • data

     : Enthält Informationen zum Envelope, der das Ereignis ausgelöst hat.

3. Payload-Beispiele: Hier sind Beispiele für Payloads verschiedener Ereignisse:

   // 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. Umgang mit der Benachrichtigung: Wenn Ihr Server eine Webhook-Benachrichtigung empfängt:
   • Überprüfen Sie die Payload, um sicherzustellen, dass es sich um eine gültige Webhook-Benachrichtigung handelt.
   • Extrahieren Sie die relevanten Informationen aus der Payload.
   • Führen Sie die erforderlichen Aktionen basierend auf dem Ereignistyp aus (z. B. Aktualisieren Ihrer Datenbank, Benachrichtigen von Benutzern, Auslösen anderer Prozesse).

   • Senden Sie eine 

     200 OK

     -Antwort, um den Empfang des Webhooks zu bestätigen.

Sign.Plus-Webhooks werden ausschließlich von den folgenden autorisierten IP-Adressen gesendet:
34.65.253.117
34.65.146.131

Bewährte Vorgehensweisen

1. Sicherheit: Stellen Sie sicher, dass Ihr Webhook-Endpunkt sicher ist. Erwägen Sie, eine Authentifizierung für Ihre Webhook-URL zu implementieren.
2. Idempotenz: Gestalten Sie Ihren Webhook-Handler idempotent. Das bedeutet, dass er das gleiche Ergebnis liefern sollte, selbst wenn derselbe Webhook mehrmals empfangen wird.
3. Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung in Ihrer Webhook-Verarbeitungslogik.

Durch das Befolgen dieser Anleitung sind Sie in der Lage, Webhooks effektiv einzurichten und zu verarbeiten, sodass Ihre Anwendung Echtzeit-Updates zum Status von Envelopes in Sign.Plus erhalten kann.