Webhooks instellen voor realtime updates van Sign.Plus

Met webhooks ontvangt u realtime updates over de status van uw enveloppen in Sign.Plus. In dit artikel wordt stap voor stap uitgelegd hoe u webhooks instelt en verwerkt voor uw Sign.Plus-integratie.

Stap 1: Een webhook aanmaken

Om realtime updates te ontvangen, moet u eerst een webhook aanmaken in Sign.Plus. Zo doet u dat:

1. Bepaal een doel-URL waarop u webhookmeldingen wilt ontvangen. Dit moet een endpoint op uw server zijn dat is ingesteld om inkomende POST-verzoeken te verwerken.
2. Kies de gebeurtenis(sen) die u wilt volgen. Sign.Plus biedt de volgende webhookgebeurtenissen:
   • envelope_completed

      - Wanneer een envelop is voltooid

   • envelope_expired

      - Wanneer een envelop is verlopen

   • envelope_declined

      - Wanneer een envelop is geweigerd

   • envelope_voided

      - Wanneer een envelop ongeldig is gemaakt

3. Gebruik de Sign.Plus-API om de webhook aan te maken. U moet uw doel-URL en de gebeurtenis(sen) die u wilt volgen opgeven.

Gedetailleerde informatie over het aanmaken van een webhook met de Sign.Plus-API vindt u in de documentatie over het aanmaken van een webhook-endpoint.

Stap 2: Webhookmeldingen verwerken

Zodra u uw webhook hebt ingesteld, stuurt Sign.Plus POST-verzoeken naar de door u opgegeven URL wanneer de gevolgde gebeurtenissen zich voordoen. Dit moet u weten over het verwerken van deze meldingen:

1. Aanvraagmethode: Alle webhookmeldingen worden verzonden als HTTP 

   POST

    verzoeken.

2. Payloadstructuur: De webhookpayload is een JSON-object met twee hoofdsecties:
   • hook

     : bevat metadata over de webhook zelf.

   • data

     : bevat informatie over de envelop die de gebeurtenis heeft geactiveerd.

3. Payloadvoorbeelden: Hier volgen voorbeelden van payloads voor verschillende gebeurtenissen:

   // 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. De melding verwerken: Wanneer uw server een webhookmelding ontvangt:
   • Controleer de payload om te bevestigen dat het een geldige webhookmelding is.
   • Haal de relevante informatie uit de payload.
   • Voer de benodigde acties uit op basis van het gebeurtenistype (bijvoorbeeld uw database bijwerken, gebruikers informeren of andere processen starten).

   • Stuur een 

     200 OK

      antwoord om de ontvangst van de webhook te bevestigen.

Sign.Plus-webhooks worden alleen verzonden vanaf de volgende geautoriseerde IP-adressen:
34.65.253.117
34.65.146.131

Aanbevolen werkwijzen

1. Beveiliging: Zorg ervoor dat uw webhook-endpoint beveiligd is. Overweeg authenticatie te implementeren voor uw webhook-URL.
2. Idempotentie: Ontwerp uw webhook-handler zo dat deze idempotent is. Dit betekent dat deze dezelfde uitkomst oplevert, ook als dezelfde webhook meerdere keren wordt ontvangen.
3. Foutafhandeling: Implementeer robuuste foutafhandeling in de verwerkingslogica van uw webhook.

Door deze handleiding te volgen, kunt u webhooks effectief instellen en afhandelen, zodat uw applicatie realtime updates ontvangt over de status van enveloppen in Sign.Plus.