Webhooki umożliwiają otrzymywanie aktualizacji w czasie rzeczywistym dotyczących statusu Twoich kopert w Sign.Plus. Ten artykuł przeprowadzi Cię przez proces konfigurowania i obsługi webhooków w integracji z Sign.Plus.
Krok 1: Utwórz webhook
Aby zacząć otrzymywać aktualizacje w czasie rzeczywistym, najpierw musisz utworzyć webhook w Sign.Plus. Oto jak to zrobić:
- Zdecyduj, jaki będzie docelowy adres URL, pod który mają być wysyłane powiadomienia webhook. Powinien to być punkt końcowy na Twoim serwerze, skonfigurowany do obsługi przychodzących żądań POST.
- Wybierz zdarzenie(-a), które chcesz śledzić. Sign.Plus oferuje następujące zdarzenia webhook:
-
envelope_completed- Gdy koperta zostanie ukończona
-
envelope_expired- Gdy koperta wygaśnie
-
envelope_declined- Gdy koperta zostanie odrzucona
-
envelope_voided- Gdy koperta zostanie unieważniona
-
- Użyj API Sign.Plus, aby utworzyć webhook. Musisz podać docelowy adres URL oraz zdarzenie(-a), które chcesz śledzić.
Aby uzyskać szczegółowe informacje na temat tworzenia webhooka za pomocą API Sign.Plus, zapoznaj się z dokumentacją punktu końcowego do tworzenia webhooka.
Krok 2: Obsługa powiadomień webhook
Po skonfigurowaniu webhooka Sign.Plus będzie wysyłać żądania POST na podany adres URL za każdym razem, gdy wystąpią śledzone zdarzenia. Oto, co musisz wiedzieć na temat obsługi tych powiadomień:
-
Metoda żądania: Wszystkie powiadomienia webhook są wysyłane jako żądania
POST.
-
Struktura ładunku: Ładunek webhooka jest obiektem JSON zawierającym dwie główne sekcje:
-
hook: Zawiera metadane dotyczące samego webhooka.
-
data: Zawiera informacje o kopercie, która wywołała zdarzenie.
-
-
Przykłady ładunków: Poniżej znajdują się przykłady ładunków dla różnych zdarzeń:
// 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"
}
} -
Obsługa powiadomienia: Gdy Twój serwer otrzyma powiadomienie webhook:
- Zweryfikuj ładunek, aby upewnić się, że jest to prawidłowe powiadomienie webhook.
- Wyodrębnij odpowiednie informacje z ładunku.
- Wykonaj niezbędne działania na podstawie typu zdarzenia (np. zaktualizuj bazę danych, powiadom użytkowników, wywołaj inne procesy).
-
Wyślij odpowiedź
200 OK, aby potwierdzić odebranie webhooka.
Webhooki Sign.Plus będą wysyłane wyłącznie z następujących autoryzowanych adresów IP:
34.65.253.117
34.65.146.131
Najlepsze praktyki
- Bezpieczeństwo: Zadbaj o to, aby punkt końcowy webhooka był bezpieczny. Rozważ wdrożenie uwierzytelniania dla adresu URL webhooka.
- Idempotencja: Zaprojektuj obsługę webhooka tak, aby była idempotentna. Oznacza to, że powinna dawać ten sam wynik nawet w przypadku wielokrotnego otrzymania tego samego webhooka.
- Obsługa błędów: Wdróż solidną obsługę błędów w logice przetwarzania webhooków.
Postępując zgodnie z tym przewodnikiem, będziesz w stanie skutecznie skonfigurować i obsługiwać webhooki, co pozwoli Twojej aplikacji na otrzymywanie aktualizacji statusów kopert w czasie rzeczywistym w Sign.Plus.