Gerçek zamanlı Sign.Plus güncellemeleri için webhook kurulumu

Webhook'lar, Sign.Plus'taki zarflarınızın durumu hakkında gerçek zamanlı güncellemeler almanızı sağlar. Bu makale, Sign.Plus entegrasyonunuz için webhook'ları ayarlama ve işleme sürecinde size yol gösterecektir.

Adım 1: Webhook oluşturun

Gerçek zamanlı güncellemeleri almaya başlamak için önce Sign.Plus'ta bir webhook oluşturmanız gerekir. Nasıl yapılacağı aşağıda açıklanmıştır:

1. Webhook bildirimlerini almak istediğiniz hedef URL'yi belirleyin. Bu, sunucunuzda gelen POST isteklerini işleyecek şekilde ayarlanmış bir uç nokta olmalıdır.
2. Takip etmek istediğiniz olay(lar)ı seçin. Sign.Plus aşağıdaki webhook olaylarını sunar:
   • envelope_completed

      - Bir zarf tamamlandığında

   • envelope_expired

      - Bir zarfın süresi dolduğunda

   • envelope_declined

      - Bir zarf reddedildiğinde

   • envelope_voided

      - Bir zarf geçersiz kılındığında

3. Webhook'u oluşturmak için Sign.Plus API'sini kullanın. Hedef URL'nizi ve takip etmek istediğiniz olay(lar)ı belirtmeniz gerekir.

Sign.Plus API'sini kullanarak webhook oluşturma hakkında ayrıntılı bilgi için Webhook oluşturma uç noktası belgelerine bakın.

Adım 2: Webhook bildirimlerini işleyin

Webhook'unuzu ayarladıktan sonra, takip edilen olaylar gerçekleştiğinde Sign.Plus belirttiğiniz URL'ye POST istekleri gönderecektir. Bu bildirimleri işleme konusunda bilmeniz gerekenler şunlardır:

1. İstek Yöntemi: Tüm webhook bildirimleri HTTP 

   POST

    istekleri olarak gönderilir.

2. Veri Yükü Yapısı: Webhook veri yükü, iki ana bölüm içeren bir JSON nesnesidir:
   • hook

     : Webhook'un kendisi hakkında meta veriler içerir.

   • data

     : Olayı tetikleyen zarf hakkında bilgiler içerir.

3. Veri Yükü Örnekleri: Farklı olaylar için veri yükü örnekleri aşağıdadır:

   // 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. Bildirimi İşleme: Sunucunuz bir webhook bildirimi aldığında:
   • Geçerli bir webhook bildirimi olduğundan emin olmak için veri yükünü doğrulayın.
   • Veri yükünden ilgili bilgileri çıkarın.
   • Olay türüne göre gerekli işlemleri gerçekleştirin (ör. veritabanınızı güncelleyin, kullanıcıları bilgilendirin, diğer süreçleri tetikleyin).

   • Webhook'un alındığını onaylamak için 

     200 OK

      yanıtı gönderin.

Sign.Plus webhook'ları yalnızca aşağıdaki yetkili IP adreslerinden gönderilecektir:
34.65.253.117
34.65.146.131

En iyi uygulamalar

1. Güvenlik: Webhook uç noktanızın güvenli olduğundan emin olun. Webhook URL'niz için kimlik doğrulama uygulamayı değerlendirin.
2. İdempotans: Webhook işleyicinizi idempotent olacak şekilde tasarlayın. Bu, aynı webhook birden fazla kez alınsa bile aynı sonucu üretmesi gerektiği anlamına gelir.
3. Hata Yönetimi: Webhook işleme mantığınızda güçlü bir hata yönetimi uygulayın.

Bu kılavuzu izleyerek webhook'ları etkili biçimde kurabilir ve yönetebilirsiniz; böylece uygulamanız Sign.Plus içindeki zarfların durumlarına ilişkin gerçek zamanlı güncellemeleri alabilir.