Webhook Abonelikleri API
Webhook yönetimi JWT ile ADMIN rolü ve settings sayfa iznini veya Enterprise
planında webhooks:manage izinli kurum API anahtarını kabul eder. Anahtar
X-API-Key ya da Authorization: Bearer başlığında gönderilir. Starter ve
Professional anahtarları bu izinle erişemez; JWT rol ve sayfa izinleri korunur.
Organizasyon kimliği sunucuda doğrulanmış kimlik bağlamından çözülür ve bütün
çağrılarda WEBHOOKS özelliği denetlenir. Organizasyon kapsamı dışındaki veya
silinmiş abonelik, olmayan kimlikle aynı 404 yanıtını döndürür. Yol parametresi
id metindir; UUID biçimi zorunlu değildir.
Uç Noktalar
Yolların başına https://api.mevzuatradar.com eklenir. Tablodaki sayfa izni,
settings sayfasına aittir; ADMIN rolü ayrıca zorunludur.
| HTTP yöntemi | Yol | Sayfa izni | Başarı / data |
|---|---|---|---|
GET | /api/v1/webhooks | Okuma | 200; abonelik dizisi, sayfalama yok |
POST | /api/v1/webhooks | Yazma | 201; abonelik, secret, revealedOnce: true |
GET | /api/v1/webhooks/:id | Okuma | 200; abonelik ve son 20 teslimat |
PUT | /api/v1/webhooks/:id | Yazma | 200; güncellenmiş abonelik |
DELETE | /api/v1/webhooks/:id | Yazma | 200; { deleted: true } |
POST | /api/v1/webhooks/:id/test | Yazma | 201; { deliveryId } |
POST | /api/v1/webhooks/:id/rotate-secret | Yazma | 201; abonelik, secret, rotated: true, revealedOnce: true |
GET | /api/v1/webhooks/:id/deliveries | Okuma | 200; { items, meta } |
Başarılı yanıtlar { "success": true, "data": ... } zarfıyla döner.
Tarayıcı kaynaklı yazma isteklerinde ayrıca CSRF çereziyle eşleşen
X-CSRF-Token ve izin verilen kaynak adresi gerekir. Başlıktaki JWT bu
middleware kontrolünü kaldırmaz.
İstek Gövdesi
| Alan | Oluşturma (POST) | Güncelleme (PUT) |
|---|---|---|
url | Zorunlu metin; protokollü URL, en fazla 2048 karakter | İsteğe bağlı; aynı doğrulama |
events | Zorunlu enum dizisi; 1–10 öğe | İsteğe bağlı enum dizisi; en fazla 10 öğe, boş dizi kabul edilir |
description | İsteğe bağlı metin; en fazla 500 karakter | İsteğe bağlı; aynı doğrulama |
includeChildOrgEvents | İsteğe bağlı JSON boolean; varsayılan false | İsteğe bağlı JSON boolean |
status | Oluşturma DTO’sunda yok | İsteğe bağlı; ACTIVE, PAUSED, DISABLED |
PUT kısmî güncellemedir; gönderilmeyen alan korunur. Tanımlanmamış gövde
alanları 400 döner. description kırpılır, boş metin null olarak saklanır.
Boolean alanı JSON true veya false olarak gönderilir; metin olarak gönderilmez.
Üretimde URL HTTPS olmalı; URL ve DNS çözümlemesi dış istek güvenlik denetiminden geçmelidir. İç ağa veya geri döngü adreslerine yönelen hedefler kabul edilmez. Teslimatta URL yeniden denetlenir ve yönlendirmeler takip edilmez.
Oluşturma ve DISABLED durumundan yeniden etkinleştirme sırasında abonelik
limiti denetlenir. ACTIVE ve PAUSED kayıtları limit hesabına dahildir;
limit ve ek hak bakiyesi organizasyonun abonelik bağlamından çözülür.
includeChildOrgEvents=true, genel olay dağıtımında doğrudan bağlı alt
organizasyonların olaylarının ana organizasyon alıcısına da yönlenmesini açar.
Gövdenin organization_id alanı kaynak organizasyonu, target_organization_id
alanı hedef organizasyonu belirtir. REGULATION_CLASSIFICATION_COMPLETED
ayrı bildirim akışını kullanır; bu seçenek o akışta aynı yönlendirmeyi sağlamaz.
Olay Kataloğu
Değerler Prisma WebhookEventType enum’u ve paylaşılan olay kataloğuyla aynıdır.
11 tür bulunur; tek aboneliğin DTO sınırı 10 türdür.
| Olay | İçerik |
|---|---|
NEW_REGULATION | Yeni mevzuat bildirimi |
REGULATION_UPDATED | Mevzuat güncelleme bildirimi |
REGULATION_CLASSIFICATION_COMPLETED | Terminal sektör sınıflandırması bildirimi |
ACTION_DEADLINE_APPROACHING | Aksiyon vadesinin yaklaşması |
IMPACT_ASSESSMENT_CREATED | Etki analizi oluşturulması |
QUALITY_SLA_BREACH | Kalite SLA ihlali bildirimi |
VERIFICATION_COMPLETED | Doğrulama çalışmasının tamamlanması |
VERIFICATION_REVIEW_REQUIRED | Doğrulama için inceleme gereksinimi |
BOARD_REPORT_READY | Yönetim kurulu raporunun hazır olması |
EVIDENCE_PACK_READY | Kanıt paketinin hazır olması |
ARTICLE_DIFF_CREATED | Madde farkının oluşturulması |
INTEGRATION_GRANT_REVOKED platformun iç sistem olayıdır: bir entegrasyon izni
iptal edildiğinde üretilir. Müşteri webhook aboneliği bu olayı seçemez; seçim
400 döner ve kurum uç noktalarına teslim edilmez. Bu yüzden yukarıdaki 11
abone olunabilir türe ve test çağrısına dahil değildir.
Test çağrısında isteğe bağlı eventType gönderilir. Alan yoksa NEW_REGULATION
kullanılır. Seçilen olaya abonelik yoksa veya enum dışı değer gönderilirse 400
döner. 11 türün her biri sabit, sentetik örnek veriler ve test: true taşır;
gerçek müşteri kayıtları test gövdesine alınmaz. deliveryId kuyruğa alınmayı
gösterir; alıcıya ulaşıldığını kanıtlamaz. Etkin olmayan alıcıda teslimat
ABANDONED olarak sonlanır.
{ "eventType": "REGULATION_UPDATED" }Anahtarlı çağrılar apikey hız sınırına tabidir (dakikada 600); limitte 429
ve Retry-After, hız sayacı kullanılamadığında 503 döner. JWT çağrıları mevcut
okuma/yazma hız sınırlarını kullanır. Tarayıcı kaynaklı çağrılarda API anahtarı da
CSRF kontrolünü kaldırmaz; sunucudan yapılan, tarayıcı kaynak başlıkları taşımayan
çağrılara ayrıca CSRF token gerekmez. Oluşturma, güncelleme, silme, sır yenileme
ve test gönderimi iki kimlik yolunda da aynı denetim eylemini üretir; denetim
metaverisine sır, URL yolu ve sorgusu alınmaz.
Sektör Sınıflandırması
REGULATION_CLASSIFICATION_COMPLETED, güncel ACCEPTED sonucu veya güncel
kabul edilmiş sonuç yokken terminal UNCLASSIFIED sonucu için gönderilebilir.
Ara ve inceleme gerektiren durumlar teslimata uygun değildir; geçmiş veri
backfill çalışmaları müşteri teslimatı üretmez. Gönderim anında içerik,
sınıflandırma, kaynak yetkisi ve yayın uygunluğu yeniden denetlenir.
Gövde classificationRunId, classificationStatus, event_id, event_version,
organization_id, regulationId, sourceCode, sourceType alanlarını içerir.
classificationStatus, bu akışta ACCEPTED, UNCLASSIFIED veya eski giriş
akışından gelen kayıtlar için LEGACY_INGRESS olabilir. Gerektiğinde
sectorDecisionVerificationLabel ve sectorDecisionVerificationTier eklenir.
Alıcı gövdeyi sabit bir data nesnesi içine yerleştirilmiş varsaymaz.
İmza ve Teslimat Başlıkları
Sunucu alıcıya JSON gövdeli POST gönderir. İmza UTF-8 ham gövde baytlarından
hesaplanır; JSON’u ayrıştırıp yeniden serileştirmek aynı imzayı garanti etmez.
| Başlık | Değer / hesaplama |
|---|---|
Content-Type | application/json |
X-Webhook-Signature-V2 | t=<unix saniye>,v1=<hex>; HMAC SHA-256 girdisi "<t>." + ham gövde |
X-Webhook-Timestamp | Unix saniye cinsinden gönderim zamanı |
X-Webhook-Signature | sha256=<hex>; yalnız ham gövde üzerinden eski HMAC SHA-256 imzası |
X-Webhook-Event | Olay türü |
X-Webhook-Event-Version | Olay sürümü; mevcut göndericilerde 1 |
X-Webhook-Delivery-Id | Teslimat kimliği |
X-Webhook-Idempotency-Key | Alıcıda tekrar işlemeyi önlemek için saklanan anahtar |
X-Webhook-Attempt | Birden başlayan genel teslimat deneme numarası |
V2 alıcı doğrulaması imzaya bağlı zaman damgasını ve sabit süreli imza
karşılaştırmasını kullanır; paylaşılan doğrulayıcının varsayılan toleransı
300 saniyedir. Ayrıntılı alıcı örnekleri Webhook Akışı sayfasındadır.
Yeni genel teslimat 10 saniyelik zaman aşımı ve en fazla 7 gönderim
denemesi kullanır. Gecikmeler 30 saniye, 2 dakika, 10 dakika, 1 saat,
6 saat, 12 saattir (toplam 19:12:30); HTTP 2xx başarıdır.
Eski satırlar kendi dört denemelik bütçesini korur. event_version=1 değişmez;
gövdeye occurred_at (varsa saklanan olayın zamanı, aksi halde kuyruk zamanı)
ve livemode (testte false) eklenir. Yeni gövde alanları her iki imzaya da
dahildir. Takvim bitince ABANDONED terminaldir; eksik dönemi
olay akışından aynı event_id ile doldurun.
Ayrı replay ucu yoktur. Günlük saklama sayımı varsayılan dry-run’dır; açık silme
seçimiyle başarılı satırlar 30, ABANDONED/FAILED satırlar 90 günden sonra
kurum kapsamında 1000 kimliklik partilerle silinir. Bekleyen/tekrar deneyen ve
kilitli satırlar korunur. Sınıflandırma bildiriminin ayrı teslimat
akışında HTTP 408, 429 ve 5xx yeniden denenebilir; sonucu belirsiz dış
istekler körlemesine yeniden gönderilmez. Alıcı kalıcı idempotency kaydı tutar.
Yanıt Alanları ve Gizli Değerler
Abonelik alanları: id, organizationId, url, description, events,
status, failureCount, consecutiveFailures, lastDeliveredAt,
includeChildOrgEvents, previousSecretExpiresAt, createdAt, updatedAt.
Tarihler ISO 8601 tarih-saat olarak döner; description, lastDeliveredAt,
previousSecretExpiresAt alanları null olabilir.
Listeye deliveryCount ve lastDelivery eklenir. lastDelivery,
{ status, httpStatus, deliveredAt, createdAt } veya null olur. Detay ise
deliveries dizisinde son 20 teslimatın tam kayıtlarını içerir.
Teslimat listesi page (en az 1, varsayılan 1) ve limit (1–100,
varsayılan 20) kabul eder. Sıralama createdAt azalandır;
data.meta={ page, limit, total, totalPages }, totalPages en az 1 olur.
Liste ve detay teslimat kayıtları id, endpointId, deliveryLedgerId,
eventType, eventVersion, idempotencyKey, payload, httpStatus,
responseBody, attempt, maxAttempts, status, nextRetryAt, lockedAt,
lockedBy, outboundAttemptStartedAt, deliveredAt, error, durationMs,
createdAt alanlarını döndürür. Durum değerleri PENDING, SUCCESS, FAILED,
RETRYING, ABANDONED olur. payload ve alıcı yanıtı hassas veri içerebilir.
secret, yalnız oluşturma ve döndürme yanıtında gösterilir. Her iki işlem
revealedOnce: true döndürür; normal liste/detay/güncelleme yanıtında gizli
değer yoktur. Döndürmede önceki değer 24 saatlik süreyle sunucuda tutulur;
previousSecretExpiresAt bu süreyi gösterir. Yeni gönderimler güncel gizli
değerle imzalanır. Gizli değerler log veya destek kaydına yazılmaz.
Hata Kodları
| HTTP durumu | Anlam |
|---|---|
400 | Geçersiz URL, olay, DTO alanı veya teslimat sayfalaması |
401 | JWT veya API anahtarı eksik/geçersiz, anahtar süresi dolmuş veya iptal edilmiş |
402 | JWT oturumunun aboneliği ürün erişimine kapalı veya bulunamıyor |
403 | ADMIN rolü, sayfa/özellik izni, organizasyon erişimi, CSRF veya abonelik limiti denetimi başarısız |
404 | Abonelik yok, silinmiş veya organizasyon kapsamında değil |
429 | İstek hızı aşıldı; Retry-After ile tekrar zamanı |
503 | Anahtarlı isteğin hız sayacı kullanılamıyor |
Hatalar application/problem+json türündedir. PLAN_LIMIT_REACHED mesaj öneki
ayrı bir errorCode alanıyla aynı kabul edilmez; ortak hata alanları
Ortak API Kuralları sayfasındadır.
Örnekler
Kurumun kendisine ait, güvenlik denetiminden geçen HTTPS alıcı adresi
WEBHOOK_RECEIVER_URL değişkeninde bulunur. Aşağıdaki komut oluşturma isteğidir:
curl --fail-with-body -X POST 'https://api.mevzuatradar.com/api/v1/webhooks' \
-H "Authorization: Bearer $MEVZUATRADAR_JWT" \
-H 'Content-Type: application/json' \
--data "{\"url\":\"$WEBHOOK_RECEIVER_URL\",\"events\":[\"NEW_REGULATION\"],\"includeChildOrgEvents\":false}"Enterprise API anahtarıyla test örneği (abonelik REGULATION_UPDATED seçmelidir):
curl --fail-with-body -X POST "https://api.mevzuatradar.com/api/v1/webhooks/$WEBHOOK_ENDPOINT_ID/test" \
-H "X-API-Key: $MEVZUATRADAR_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"eventType":"REGULATION_UPDATED"}'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, REGULATION_UPDATED, ARTICLE_DIFF_CREATED ve
IMPACT_ASSESSMENT_CREATED 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.
ARTICLE_DIFF_CREATED: articleCount, regulationId, sourceKind, sourceType,
versionCount, app_url, public_url. IMPACT_ASSESSMENT_CREATED: assessmentId,
regulationId, impactLevel, departments, complianceDeadline, app_url, public_url.
Scraper-only runtime’da bu iki olay için ek kamu sorgusu yapılmaz; public_url: null olur.