Webhook Akışı
Webhook’lar mevzuat ve uyum olaylarını kayıtlı alıcı URL’sine JSON gövdeli
POST isteğiyle iletir. Yönetim uçları JWT ile ADMIN rolü ve settings
sayfa iznini veya Enterprise planında webhooks:manage izinli kurum API
anahtarını kabul eder. Her iki yol webhooks özellik hakkını, kurum kapsamını,
URL güvenlik denetimini ve kotayı aynı serviste uygular. JWT okumaları
settings:read, değişiklikleri settings:write izniyle korunur.
Abonelik Yönetimi
| İşlem | API yolu |
|---|---|
| Listeleme / oluşturma | GET / POST /api/v1/webhooks |
| Ayrıntı / güncelleme / silme | GET / PUT / DELETE /api/v1/webhooks/:id |
| Test olayı kuyruğa alma | POST /api/v1/webhooks/:id/test |
| İmza anahtarını yenileme | POST /api/v1/webhooks/:id/rotate-secret |
| Teslimat geçmişi | GET /api/v1/webhooks/:id/deliveries |
Oluşturmada url ve boş olmayan events dizisi zorunludur. URL en fazla
2.048 karakter, olay dizisi en fazla 10 öğe, isteğe bağlı description en
fazla 500 karakterdir. includeChildOrgEvents varsayılanı false olur.
Üretimde HTTPS ve dış istek güvenlik kontrolü uygulanır; özel ağ adresleri
kullanılmaz. Teslimat yönlendirmeleri takip etmez; alıcı URL’si doğrudan
isteği karşılar.
Gövde şemaları, olay kataloğu ve hata ayrıntıları Webhook Abonelikleri API sayfasındadır. Katalogda bir olayın bulunması, her kurum için o olayın mutlaka üretileceğini göstermez; abonelik, kurum bağlamı ve ilgili özelliğin hakkı ayrıca değerlendirilir.
Tarayıcı kaynaklı yazma çağrılarında JWT yanında CSRF çereziyle eşleşen
X-CSRF-Token ve izin verilen kaynak adresi de gerekir. Ayrıntılar
Kimlik Doğrulama sayfasındadır.
Olay Gövdesi
NEW_REGULATION, canlı taramayla gelen ve bildirimleri bastırılmamış her yeni
mevzuat için sınıflandırma tamamlandıktan sonra gönderilir. İki mevzuat iki ayrı
olay üretir; classificationStatus değeri COMPLETED olur.
event_id kararlı, opak bir kimliktir; aynı mevzuat için yeniden gönderimde aynı
kalır. Eski new-regulation:<kaynak>:<iş> biçimine güvenmeyin veya kimliği
ayrıştırmayın. Aynı olay GET /api/v1/events akışında
aynı event_id ile bulunur; akış öğesinin payload alanı webhook’un data
nesnesiyle aynıdır. Aynı yayının yeniden işlenmesi ikinci olay veya ikinci
webhook teslimi oluşturmaz.
Aşağıdaki örnek tek mevzuatın tamamlanmış yayın olayını gösterir.
{
"event_id": "evt_7f39a2c81b9045e6",
"event_version": 1,
"occurred_at": "2026-10-24T09:00:00.000Z",
"livemode": true,
"sent_at": "2026-10-24T09:00:00.000Z",
"organization_id": "org_01",
"target_organization_id": "org_01",
"data": {
"sourceType": "GIB",
"sourceCode": "GIB",
"regulationIds": ["reg_01"],
"classificationStatus": "COMPLETED",
"docsFound": 1,
"docsNew": 1
}
}organization_id kaynak kurumu, target_organization_id hedef aboneliğin
kurumunu temsil eder; alt kurum olaylarında farklı olabilir. Bu örnek bütün
olaylar için sabit şema değildir. Örneğin test isteği test: true içerir ve
data.regulationId kullanır. Olay türü X-Webhook-Event başlığından okunur;
bütün gövdelerde type alanı bulunduğu varsayılmaz.
İmza Başlıkları
| Başlık | Açıklama |
|---|---|
X-Webhook-Signature-V2 | t=<unix saniye>,v1=<hex>; "<t>.<ham gövde>" üzerinden HMAC SHA-256 |
X-Webhook-Timestamp | V2 imzasındaki t ile aynı zaman |
X-Webhook-Signature | Eski uyumluluk imzası: sha256=<hex>; yalnız ham gövdeyi imzalar |
X-Webhook-Event | Örneğin NEW_REGULATION veya REGULATION_CLASSIFICATION_COMPLETED |
X-Webhook-Event-Version | Olay sözleşme sürümü |
X-Webhook-Delivery-Id | Teslimat kimliği |
X-Webhook-Idempotency-Key | Tekrarlanan teslimatın aynı işlem olarak ele alınması için anahtar |
Alıcı JSON ayrıştırmadan önce ham istek baytlarını doğrular. JSON’u yeniden oluşturmak veya boşluklarını değiştirmek imzayı bozar. V2 yalnız zaman ve gövdeyi imzalar; diğer başlıkları imzalamaz. İmzalı zamanın şimdiki zamandan mutlak farkı en fazla 300 saniye kabul edilir; saat eşitlemesi gereklidir. Eski gövde imzası zaman aşımına karşı koruma sağlamaz. V2 doğrulaması başarısız olduğunda eski imzaya otomatik geçiş yapılmaz.
HMAC Doğrulaması
Aşağıdaki Node.js işlevi apps/docs/examples/webhook-verify-v2.js ile aynıdır:
const { createHmac, timingSafeEqual } = require('node:crypto');
function verifyWebhookV2(
rawBody,
header,
secret,
nowSeconds = Math.floor(Date.now() / 1000),
) {
if (!Buffer.isBuffer(rawBody) || typeof header !== 'string' || !secret)
return false;
const match = /^t=([0-9]+),v1=([a-f0-9]{64})$/i.exec(header);
if (!match) return false;
const timestamp = Number(match[1]);
if (
!Number.isSafeInteger(timestamp) ||
Math.abs(nowSeconds - timestamp) > 300
)
return false;
const expected = createHmac('sha256', secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}Python karşılığı apps/docs/examples/webhook_verify_v2.py dosyasındadır.
Her iki örnek dispatcher’ın t=...,v1=... biçimini kabul eder. Node.js ve
Python alıcı örnekleri V2 doğrular; bellekte tuttukları tekrar kayıtları yalnız
gösterim içindir. Üretim alıcısı, doğrulanmış olayı ve işlem anahtarını kalıcı
kuyruk/işlem kaydına atomik olarak yazar; aynı olayın yan etkisini yeniden
uygulamaz. Yalnız imza kontrolü 300 saniye içindeki tekrarları engellemez.
Teslimat ve Yeniden Deneme
Genel Webhook kuyruğu için davranış:
- Alıcı
2xxdöndürürse teslimat başarılıdır. İstek zaman aşımı 10 saniyedir. - Ağ hatası, zaman aşımı ve
2xxdışındaki yanıtlar başarısız sayılır;4xxyanıtlar da buna dahildir. - Yeni genel teslimatlarda ilk gönderim dahil en fazla yedi deneme vardır. Başarısız denemelerden sonra sırasıyla 30 saniye, 2 dakika, 10 dakika, 1 saat, 6 saat ve 12 saat beklenir: toplam 19 saat 12 dakika 30 saniye. Kuyruk yoğunluğu gerçek gönderim zamanını geciktirebilir. Önceden kuyruğa alınmış dört denemelik satırlar kendi bütçesiyle tamamlanır.
X-Webhook-Attemptdeneme numarasını1ile başlayarak bildirir.event_versiondeğeri1kalır. Additiveoccurred_at, varsa saklanan olayın zamanını, aksi halde kuyruğa alınma zamanını taşır;livemodesaklanan olaydan gelir, test teslimatlarındafalseolur. Bu iki gövde alanı ham gövde üzerinden hesaplanan eski imzaya ve V2 imzaya dahildir.- Her deneme güncel zamanla ve o anda geçerli anahtarla yeniden imzalanır;
aynı teslimatın idempotency anahtarı korunur. Alıcının
Retry-Afterbaşlığı bu kuyruğun bekleme takvimini değiştirmez. - Bütçe bittiğinde kayıt
ABANDONEDolur. Silinmiş veyaACTIVEolmayan endpointin bekleyen teslimatı daABANDONEDyapılır. - Takvimi aşan kesintide olay akışından eksik dönemi
aynı
event_idile doldurun; ayrı replay ucu yoktur. Beş saat kapalı alıcı, kuyruk gecikmesi yoksa altıncı denemede yaklaşık 7 saat 12 dakika 30 saniyede teslim alabilir. Olay akışının erişim ve 30 günlük saklama sınırları geçerlidir. - Genel kuyrukta 100 ardışık hata endpointi
DISABLEDyapar; başarılı teslimat ardışık hata sayacını sıfırlar. Süreye bağlı otomatik yeniden etkinleşme uygulanmaz; yönetici sorunu giderip endpoint durumunu günceller.
REGULATION_CLASSIFICATION_COMPLETED için sektör bildirim teslimat defteri
ayrı çalışır. HTTP hatalarında yalnız 408, 429 ve 5xx yeniden denenir;
diğer HTTP hataları terminaldir. Dört denemelik bütçede bekleme 1, 2 ve
4 saniyedir; dış isteğin sonucu belirsizse kör yeniden deneme yapılmaz.
Genel kuyruğun yedi denemelik takvimi bu akışa uygulanmaz. Buna karşılık
100 ardışık hata sayacı ve başarıda sıfırlama iki akışta da aynı servisle
işletilir.
Teslimat Geçmişi ve Test
Günlük genel worker saklama işi varsayılan olarak yalnız dry-run sayımı yapar;
silme operatörün açık uygulama seçimiyle etkinleşir. Başarılı teslimat satırları
30 günden, ABANDONED/FAILED satırlar 90 günden eskiyse saklama adayıdır.
Tam eşikteki satırlar korunur. PENDING, RETRYING ve kilitli satırlar silinmez;
silme kurum kapsamında en fazla 1000 kimliklik partilerle yapılır.
GET /api/v1/webhooks/:id/deliveries?page=1&limit=20 çağrısında page en az
1, limit 1–100 aralığındadır. Yanıt success: true zarfı içinde
data.items ve data.meta döndürür. Kayıtlar en yeniden eskiye sıralanır.
HTTP durumu, attempt, maxAttempts, status, nextRetryAt ve hata
alanlarına ek olarak olay gövdesi ve alıcı yanıtı da bulunabilir. Bu geçmiş
kişisel veriden arındırılmış bir özet olarak kabul edilmez; alıcı hata
sayfaları veya yanıtları hassas içerik taşımamalıdır.
Test çağrısı data.deliveryId döndürür; kuyruğa alınması alıcının isteği
kabul ettiğini kanıtlamaz. Sonuç teslimat geçmişinden kontrol edilir.
İmza Anahtarı Yenileme
Oluşturma ve rotate-secret yanıtlarında yeni secret gösterilir; normal
endpoint listesi ve ayrıntı alanlarına eklenmez. Yenilemede önceki anahtar
24 saatlik sona erme bilgisiyle saklanır. Temizleme listeleme/ayrıntı okuması
sırasında yapılır; tam süre sonunda çalışan ayrı bir silme görevi varsayılmaz.
Gönderici yenilemeden sonra yalnız yeni anahtarla imzalar. Eski anahtarın
saklanması iki imza gönderildiği veya alıcının kendiliğinden yenilendiği
anlamına gelmez. Alıcı yeni anahtarı güvenli kanaldan alır; geçişte önceki ve
yeni anahtarı süreli olarak doğrulayabilir. Önceki anahtarları süresiz kabul
etmez; secret değerleri URL’ye, istemci tarafı koda ve günlüklere yazılmaz.
Olay Türüne Göre Test
POST /api/v1/webhooks/:id/test gövdesindeki isteğe bağlı eventType, abone
olduğunuz 11 olay türünden birini seçer. Gönderilmezse NEW_REGULATION
kullanılır. Abone olunmayan veya geçersiz tür 400 döner. Örnek gövdeler sabit
ve sentetiktir, test: true içerir. Kuyruğa alma başarısı teslimat kanıtı değildir.
API anahtarı örneği ve hız sınırları API başvurusundadır.
Tarayıcıdan gelen anahtarlı yazma çağrıları da CSRF doğrulamasından geçer.
Belge Bağlantıları
app_url, /regulation/<id> uygulama detayını açan kanonik URL’dir. Sorgu,
fragment, oturum, token, kullanıcı veya kurum kimliği taşımaz. Oturum yoksa
mevcut OTP giriş akışı aynı belgeye dönüş adresini korur; tek tıkla giriş
bağlantısı değildir. Belge erişimi ve kurum notlarının görünürlüğü mevcut
yetki kontrollerinden geçer.
public_url, yalnız kamu arşivine uygun belgede yapılandırılmış kamu kökü ve
kanonik /mevzuat/... yolunu içerir. Özel, kuruma ait, arşivlenmiş, henüz
yayımlanmamış veya desteklenmeyen kaynak belgelerinde null olur. Kamu kökü
yapılandırılmamışsa da null döner. Alanlar additive olup eski alanları korur.
Yeni NEW_REGULATION olaylarında payload / webhook data alanları
app_url ve public_url içerir; regulationIds dizisi tek belge kimliğini
korur. ACTION_DEADLINE_APPROACHING ve REGULATION_UPDATED webhook data alanı da ilgili belge
bağlantılarını taşır. Olay zarfı ve event_version: 1 değişmez. Önceden
kaydedilmiş olaylarda bu alanlar bulunmayabilir; tüketiciler bunu desteklemelidir.
Diğer olay türlerinde bağlantı alanlarının varlığını varsaymayın.
Türetilmiş Belge Olaylarının Bağlantıları
| Olay | data alanları |
|---|---|
ARTICLE_DIFF_CREATED | articleCount, regulationId, sourceKind, sourceType, versionCount, app_url, public_url |
IMPACT_ASSESSMENT_CREATED | assessmentId, regulationId, impactLevel, departments, complianceDeadline, app_url, public_url |
app_url ilgili belgenin uygulama adresidir; oturum açılması gerekebilir.
public_url yalnız kamuya açık belge projeksiyonu ve kamu kökü varsa üretilir;
özel belgede veya scraper-only runtime’da null olur. Her iki bağlantının sorgu
ve fragment bölümleri boştur; giriş anahtarı veya kişisel alan taşımaz. Eski
olaylarda bu additive alanlar bulunmayabilir; olay sözleşme sürümü 1 kalır.
Uygulama başına webhook — kapalı beta
Geliştirici firma, /settings/integrations içindeki Webhook ve teslim günlüğü
alanından her uygulama için tek uç yönetir. Firma ADMIN oturumu ile
GET/PUT/DELETE /api/v1/integration-apps/:id/webhook,
POST /api/v1/integration-apps/:id/webhook/rotate ve
GET /api/v1/integration-apps/:id/webhook/deliveries kullanılır.
Uygulama sırrıyla GET/PUT /api/v1/integration/webhook çağrısında
X-MR-Organization-Id gerekmez; LIVE uygulamanın ucunu yönetmek için canlı uygulama sırrı gerekir, test sırrı bu ucu değiştiremez; kimlik doğrulama yalnız o uygulamayı çözer.
İmza sırrı şifreli saklanır ve yalnız ilk oluşturma veya yenileme yanıtında gösterilir.
GLOBAL olaylar (NEW_REGULATION, REGULATION_UPDATED,
REGULATION_CLASSIFICATION_COMPLETED, ARTICLE_DIFF_CREATED) LIVE uygulamanın
ucuna bir kez gönderilir. Zarfın organization_id ve grant_id alanları GLOBAL
olaylarda null, ORG olaylarında hedef kurum ve aktif izin kimliğidir.
event_version 1 kalır; livemode ve mevcut zarf alanları korunur.
SANDBOX uygulamalara gerçek GLOBAL olay gönderilmez.
ORG eşlemesinin tek kaynağı INTEGRATION_WEBHOOK_EVENT_SCOPES sabitidir:
| ORG olayı | Gereken mevcut scope |
|---|---|
| ACTION_DEADLINE_APPROACHING | actions:read |
| VERIFICATION_COMPLETED | verification:read |
| VERIFICATION_REVIEW_REQUIRED | verification:read |
| BOARD_REPORT_READY | reports:read |
| EVIDENCE_PACK_READY | evidence-packs:read |
INTEGRATION_GRANT_REVOKED düzenli ORG dağıtımına alınmayan sistem bildirimidir. Bir canlı izin iptal edildiğinde yalnız o uygulamanın etkin uygulama ucuna, abonelik seçimi gerekmeden integration.grant_revoked olarak gider; kurum uçlarına asla gitmez. Gövde veri taşımaz: zarf alanları (event_id, event_type, event_version: 1, occurred_at, livemode) dışında yalnız grant_id, organization_id ve revoked_by_type (CUSTOMER, VENDOR, PLATFORM veya SYSTEM) bulunur. Sandbox izinlerinin iptali bu olayı üretmez. IMPACT_ASSESSMENT_CREATED ve QUALITY_SLA_BREACH için mevcut API izin
kataloğunda kanıtlanmış bir okuma karşılığı yoktur; bu ORG olayları gönderilmez.
Aktif grant ve uygulamanın onaylı scope’u birlikte aranır. Teslimden önce
uygulama ve grant yeniden okunur: sonlandırma/iptal terminal CANCELED, geçici
askı veya genel durdurma ise deneme tüketmeden ertelemedir. İzin iptali
bildirimi yalnız iptal nedeni için muaftır; genel durdurmadan muaf değildir.
people:read izni grant ve uygulamanın onaylı scope’unda birlikte yoksa ORG
olaylarının data alanından kişisel alanlar (assignee, createdBy)
çıkarılır.
Teslimlerde sıra garantisi yoktur. Uç başına aynı anda bir teslim yapılır;
meşgul uç diğer uygulamanın slotunu bekletmeden ertelenir. Günlük yalnız
seçili uygulamanın son 100 teslim durumunu ve bağlı kurum, son 7 gün başarı
oranı, son hata zamanı, kapalı uç sayılarını gösterir; gövde/sır göstermez.
Aynı URL kurum ucu olarak aynı firmada kayıtlıysa uygulama ucu kaydı
409 WEBHOOK_URL_ALREADY_USED döner; mevcut benzersizlik kısıtı korunur.