← Lifecycle Webhook'ları
Ne zaman & ne yaparsın
| Ne zaman | OAuth connect tamamlandı (kurulum bağlandı) |
| Geliştirici | Provision — tenant kaydını oluştur/etkinleştir |
| Abonelik / gating | Yok — bağlı (connected) her kuruluma her zaman gelir |
Envelope (tüm lifecycle/event'lerde ortak)
| Alan | Tip | Zorunlu | Açıklama |
|---|
| id | string | ✓ | Idempotency anahtarı. Aynı id tekrar gelebilir (retry) → dedup et. |
| type | string | ✓ | "app.installed" — event mi lifecycle mı olduğunu bununla ayırt et. |
| version | string | ✓ | Envelope şema versiyonu ("1"). |
| tenantId | string | ✓ | Hangi tenant (kurulum). İşlemini buna göre yap; cross-tenant doğrula. |
| occurredAt | number | ✓ | Oluşma zamanı (unix ms). |
| data | object | ✓ | Tipe özel gövde (aşağıda). |
data alanları
| Alan | Tip | Zorunlu | Açıklama |
|---|
| version | string | ✓ | Kurulan eklenti sürümü (manifest version, semver — örn. "1.1.3"). Sürüme göre davranış/migrasyon için sakla. |
| scopes | string[] | ✓ | Tenant'ın onayladığı scope listesi. Çağrılarını ve özelliklerini buna göre sınırla; eksik scope'a göre graceful degrade et. |
Tam örnek payload
Örnek webhook gövdesi (data alanı teyitli — webhook.site)
{
"id": "evt_9f2a7c1b",
"type": "app.installed",
"version": "1",
"tenantId": "tnt_123",
"occurredAt": 1780000000000,
"data": {
"version": "1.1.3",
"scopes": [
"orders:read",
"hooks:table.close"
]
}
} En iyi pratik
- Provision'ı idempotent kur: retry'da aynı id ikinci kez gelirse tenant'ı yeniden oluşturma — var olanı güncelle/no-op.
- Onaylanan scopes[]'i sakla ve yetkilerini buna göre sınırla; payload'da bekleyip de gelmeyen veri (PII) muhtemelen scope eksikliğindendir.
- version'u kaydet — sürüme özel migrasyon/feature flag için referansın budur.
- Premium'u burada AÇMA: install ≠ ödeme. Premium yetkiyi subscription.activated ile aç.