Özel webhooklar

Nasıl çalışır

Her gönderimde formbase, webhook URL’nize bir JSON gövdesi POST eder. İstek HMAC-SHA256 ile imzalanır, başarısız olursa yeniden denenir ve entegrasyonun etkinlik günlüğüne kaydedilir. Bu sayfa kurulumu anlatır. Tam payload, başlıklar ve imza algoritması webhook referansında yer alır.

Webhook ekle

1. 1

   Form Entegrasyonlarını açın

   Form → Ayarlar → Entegrasyonlar → Webhook.

2. 2

   URL

   Host ve yolu yazın — https:// öneki girişte sabittir. Düz http:// yalnızca geliştirme sırasında localhost için kabul edilir.

3. 3

   Eşleme

   Her alanı göndermek için boş bırakın. Yalnızca seçtiğiniz alanları, seçtiğiniz JSON anahtarı altında göndermek için satır ekleyin. Eşleme answers ile display’i birlikte şekillendirir, yani yeniden adlandırılan bir anahtar ikisinde de yeniden adlandırılır. Eşlemenin altındaki tam istek, siz düzenledikçe yeniden çizilir.

4. 4

   Başlıklar

   whsec_ ile başlayan bir imzalama gizli anahtarı sizin için oluşturulur. Oluşturulduktan sonra değiştirilemez. Aynı adımda uç noktanızın ihtiyaç duyduğu en fazla 5 özel başlık ekleyin, örneğin bir yetkilendirme token’ı; alıcınız fields.list çağıramıyorsa Alan listesini her olayla gönder seçeneğini açın. Content-Type otomatik ayarlanır ve geçersiz kılınamaz.

5. 5

   Sonlandır

   Sentezlenmiş bir örnek gönderimi POST etmek için Test olayı gönder’e basın, ardından Entegrasyon oluştur’a basın.

formbase’in kabul ettiği URL’ler

• Her yerde https://, geliştirme sırasında localhost ve *.localhost için ise http://.

• URL’de kimlik bilgisi olmamalı ve en fazla 2.048 karakter olmalı.

• Özel veya iç adresler kabul edilmez. Ana bilgisayar adı çözümlenir ve her teslimattan hemen önce yeniden kontrol edilir; bu yüzden kurulumdan sonra bir DNS kaydı iç bir adrese yönlendirilse bile reddedilmeye devam eder.

Reddedilen bir URL geçici değil, bir yapılandırma sorunudur: teslimat yeniden denenmez, kalıcı olarak başarısız olur.

Ne alırsınız

Her istek aynı olay zarfıdır — id, type, createdAt, apiVersion, test ve data. data içinde form, gönderim (kimlik, katılımcı e-postası, gönderim zamanı, PDF bağlantısı, dil), alan anahtarına göre anahtarlanmış bir answers nesnesi ve aynı anahtarları okunabilir metin olarak taşıyan bir display nesnesi bulunur. Her yanıt, her haritada bir kez yer alır.

Tam payload biçimi, answers ve display ve bir tekrarlayan grubun nasıl temsil edildiği için referansa bakın.

Formunuz için tam gövdeyi önizlemek üzere entegrasyonu açın ve imzalama gizli anahtarının altındaki Örnek yük’ü genişletin. Güncel eşlemenizi örnek yanıtlarla birlikte gösterir.

İmzaları doğrulama

Her istek bir X-formbase-Signature başlığı içerir: t=TIMESTAMP,sha256=HEX, imzalama gizli anahtarınızla hesaplanan TIMESTAMP.BODY’nin bir HMAC-SHA256’sı. Gizli anahtarın kendisi hiçbir zaman gönderilmez. Referansta kopyalayıp yapıştırabileceğiniz bir doğrulama kod parçası bulunur.

Terk edilmiş yanıt etkinlikleri

Özel webhooklar yalnızca tamamlanan gönderimler ve düzenlemeler için tetiklenir — terk edilmiş taslaklar için asla. Özel bir webhook, her ikisini de alan tek alıcıdır: bir Zapier, Make veya n8n aboneliği ilk gönderimleri ya da düzenlemeleri seçer, asla ikisini birden. Terk edilmiş taslaklar için bir Terk edilmiş gönderiler adımına sahip bir sağlayıcı kullanın: Google Sheets, Airtable, Notion, Slack, Discord, Linear veya GitHub Issues. Her biri kendi bekleme penceresini ve, uygulanabildiği yerde, kendi ileti şablonunu kullanır. Bu adım Pro veya Business gerektirir.

Yeniden denemeler ve hatalar

• Herhangi bir 2xx teslimatı başarılı sayılır.

• En fazla 5 deneme: ilki hemen tetiklenir, yeniden denemeler en az 1, 2, 4 ve 8 dakika bekler. formbase, süresi gelen yeniden denemeleri her 30 dakikada bir arar, bu yüzden son deneme ilkinden yaklaşık iki saat sonra gelir. Bir 429 veya 5xx üzerindeki Retry-After başlığı daha uzun bir bekleme istediğinde dikkate alınır.

• 429, 5xx, zaman aşımları ve bağlantı hataları yeniden denenir. Diğer her 4xx hemen başarısız olur.

• Art arda 5 başarısızlıktan sonra entegrasyon otomatik olarak duraklatılır ve kuran kişiye bir e-posta gider. Uç noktayı düzeltin, ardından Yeniden Etkinleştir’e basın.

• 401, 403 ve 404 entegrasyonu bir hata durumu ve aynı e-posta ile hemen durdurur — beş başarısızlığın beklenmesine gerek yoktur.

• Tüm 5 denemesini tüketen teslimatlar entegrasyonda bir banner’da toplanır. Tümünü Yeniden Dene bunları yeniden kuyruğa alır ve duraklatılmış bir entegrasyonu yeniden etkinleştirir.

Test etme

Test olayı gönder, Sonlandır adımında ve kaydedilmiş entegrasyonda tekrar görünür. Gerçek bir teslimat gibi imzalanmış ve özel başlıklarınızla birlikte sentezlenmiş bir örnek gönderimi POST eder — metin için “John Doe”, sayılar için 42, e-posta için john@example.com. Kaydedilmiş entegrasyondan çalıştırıldığında etkinlik günlüğüne ayrıca bir bağlantı testi kaydı yazar.

Yerel geliştirme için geliştirme sunucunuzu bir tünel ile dışarıya açın:

# ngrok
ngrok http 3000

# cloudflare tunnel

cloudflared tunnel --url http://localhost:3000

SSS

Sonraki adımlar