Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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

İşlemAPI yolu
Listeleme / oluşturmaGET / POST /api/v1/webhooks
Ayrıntı / güncelleme / silmeGET / PUT / DELETE /api/v1/webhooks/:id
Test olayı kuyruğa almaPOST /api/v1/webhooks/:id/test
İmza anahtarını yenilemePOST /api/v1/webhooks/:id/rotate-secret
Teslimat geçmişiGET /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ıkAçıklama
X-Webhook-Signature-V2t=<unix saniye>,v1=<hex>; "<t>.<ham gövde>" üzerinden HMAC SHA-256
X-Webhook-TimestampV2 imzasındaki t ile aynı zaman
X-Webhook-SignatureEski uyumluluk imzası: sha256=<hex>; yalnız ham gövdeyi imzalar
X-Webhook-EventÖrneğin NEW_REGULATION veya REGULATION_CLASSIFICATION_COMPLETED
X-Webhook-Event-VersionOlay sözleşme sürümü
X-Webhook-Delivery-IdTeslimat kimliği
X-Webhook-Idempotency-KeyTekrarlanan 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ı 2xx döndürürse teslimat başarılıdır. İstek zaman aşımı 10 saniyedir.
  • Ağ hatası, zaman aşımı ve 2xx dışındaki yanıtlar başarısız sayılır; 4xx yanı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-Attempt deneme numarasını 1 ile başlayarak bildirir. event_version değeri 1 kalır. Additive occurred_at, varsa saklanan olayın zamanını, aksi halde kuyruğa alınma zamanını taşır; livemode saklanan olaydan gelir, test teslimatlarında false olur. 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-After başlığı bu kuyruğun bekleme takvimini değiştirmez.
  • Bütçe bittiğinde kayıt ABANDONED olur. Silinmiş veya ACTIVE olmayan endpointin bekleyen teslimatı da ABANDONED yapılır.
  • Takvimi aşan kesintide olay akışından eksik dönemi aynı event_id ile 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 DISABLED yapar; 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ı

Olaydata alanları
ARTICLE_DIFF_CREATEDarticleCount, regulationId, sourceKind, sourceType, versionCount, app_url, public_url
IMPACT_ASSESSMENT_CREATEDassessmentId, 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_APPROACHINGactions:read
VERIFICATION_COMPLETEDverification:read
VERIFICATION_REVIEW_REQUIREDverification:read
BOARD_REPORT_READYreports:read
EVIDENCE_PACK_READYevidence-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.