Geri çağırmayı alın ve doğrulayın

REST API ile istek gönderin’deki gibi bir API token’ına ve yayınlanmış bir forma, ayrıca makinenizde Node veya Python’a ihtiyacınız var. Bir geri çağırmanın ne taşıdığı ve yeniden denemelerin nasıl çalıştığı Geri çağırmalar ve imzalama’dadır.

1. İmzalama anahtarını kopyalayın

formbase her geri çağırmayı çalışma alanınızın istek imzalama anahtarıyla imzalar. Çalışma alanı kenar çubuğunda OAuth ve API Anahtarları’nı açın ve İstek imzalama anahtarı kartını bulun:

Kopyalama düğmesine tıklayın ve anahtarı alıcınızın çalışacağı terminaldeki bir ortam değişkeninde saklayın:

export FORMBASE_SIGNING_SECRET='rqs_...'

2. Alıcıyı yazın

verify fonksiyonunu Geri çağırmalar ve imzalama’dan alıcınızın yanına kaydedin: import kullandığından Node için verify.mjs olarak, ya da Python için verify.py olarak. Alıcı ham gövdeyi okur, imzayı kontrol eder ve ancak o zaman JSON’u ayrıştırır:

import http from 'node:http'
import { verifyFormbaseCallback } from './verify.mjs'
const secret = process.env.FORMBASE_SIGNING_SECRET
http
  .createServer((req, res) => {
    const chunks = []
    req.on('data', (chunk) => chunks.push(chunk))
    req.on('end', () => {
      const rawBody = Buffer.concat(chunks).toString('utf8')
      const signature = req.headers['x-formbase-signature'] ?? ''
      if (!verifyFormbaseCallback(rawBody, signature, secret)) {
        console.log('rejected: bad signature')
        res.writeHead(401).end()
        return
      }
      const event = JSON.parse(rawBody)
      console.log(event.type, event.data.request.externalId, JSON.stringify(event.data.answers))
      res.writeHead(200).end()
    })
  })
  .listen(8787)

import json, os
from http.server import BaseHTTPRequestHandler, HTTPServer
from verify import verify_formbase_callback
SECRET = os.environ['FORMBASE_SIGNING_SECRET']
class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        raw_body = self.rfile.read(int(self.headers['Content-Length']))
        signature = self.headers.get('X-formbase-Signature', '')
        if not verify_formbase_callback(raw_body, signature, SECRET):
            print('rejected: bad signature', flush=True)
            self.send_response(401)
            self.end_headers()
            return
        event = json.loads(raw_body)
        print(event['type'], event['data']['request'].get('externalId'), event['data'].get('answers'), flush=True)
        self.send_response(200)
        self.end_headers()
HTTPServer(('', 8787), Handler).serve_forever()

Gövdeyi tam olarak geldiği şekliyle karmalayın (hash). Onu ayrıştırıp yeniden JSON’a dönüştürmek baytları değiştirir ve imza artık eşleşmez.

3. Çalıştırın ve ona genel bir URL verin

Alıcıyı başlatın:

node receiver.mjs      # or: python3 receiver.py

formbase yalnızca genel HTTPS adreslerini çağırır, bu yüzden localhost işe yaramaz. Test ederken bir tünel makinenize bir tane verir.

hesap gerektirmez. İkinci bir terminalde çalıştırın:

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

https://horn-cod-classics-arab.trycloudflare.com gibi bir adres yazdırır. ngrok ve benzeri araçlar aynı şekilde çalışır. Üretimde, bunun yerine sunucunuzun kendi HTTPS URL’sini kullanın.

4. Geri çağırma URL’siyle bir istek gönderin

Önceki kılavuzdaki gibi bir test isteği oluşturun ve tünel adresiyle callbackUrl ekleyin. Kendi form kimliğinizi kullanın:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "requests.create",
    "params": {
      "formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g",
      "recipient": { "email": "ada@acme.example", "name": "Ada Lovelace" },
      "prefill": { "company_name": "Analytical Engines Ltd" },
      "readonly": ["company_name"],
      "externalId": "supplier-2044",
      "idempotencyKey": "supplier-2044",
      "callbackUrl": "https://horn-cod-classics-arab.trycloudflare.com/formbase",
      "test": true
    }
  }'

Yeni bir idempotencyKey kullanın: farklı bir gövdeyle aynı anahtar reddedilir. Yanıttaki url’yi açın, formu yanıtlayın ve gönderin.

5. Geri çağırmanın gelişini görün

Gönderdikten birkaç saniye sonra alıcı, olay türünü, harici kimliğinizi ve yanıtları yazdırır. Node alıcısı şunu yazdırır:

request.completed supplier-2044 {"certificate_of_incorporation":[{"name":"certificate-of-incorporation.pdf","size":635,"type":"application/pdf","url":"https://api.formbase.so/api/storage/...",...}],"company_name":"Analytical Engines Ltd","contact_email":"ada@acme.example","do_you_accept_our_30_day_payment_terms":"yes","vat_number":"GB123456789"}

Bir reddi görmek için alıcıya kendiniz herhangi bir POST gönderin, örneğin curl -X POST -d ‘’ http://localhost:8787. Geçerli bir imzası yoktur, bu yüzden alıcı rejected: bad signature yazdırır ve 401 ile yanıt verir.

Canlıya çıkmadan önce

• 10 saniye içinde 2xx ile yanıt verin. formbase, herhangi bir 2xx’te geri çağırmayı teslim edilmiş sayar. Bir 5xx, 408, 429 veya zaman aşımı yaklaşık dört saat boyunca yeniden denenir; yukarıdaki 401 gibi başka herhangi bir 4xx yeniden denemeleri durdurur. Bkz. Yeniden denemeler.

• type üzerinde dallanın.

  Aynı URL ayrıca yanıtsız gelen request.expired ve request.canceled’ı da dinler.

• Her olayı bir kez işleyin. Bir yeniden deneme aynı id’yi taşır. İşlediğiniz kimlikleri saklayın ve bir tekrarı atlayın.

• test’i kontrol edin.

  Bir test isteğinden gelen geri çağırma “test”: true taşır. Gerçek alıcılar için requests.create’ten test’i çıkarın.

Alıcınız yeniden denemelerin sürdüğünden daha uzun süre kapalıysa yanıtlar kaybolmaz. Onları requests.get ile okuyun, ya da requests.replayCallback ile ya da İstekler sayfasından geri çağırmayı yeniden gönderin.

Sırada