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

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öntemiYolSayfa izniBaşarı / data
GET/api/v1/webhooksOkuma200; abonelik dizisi, sayfalama yok
POST/api/v1/webhooksYazma201; abonelik, secret, revealedOnce: true
GET/api/v1/webhooks/:idOkuma200; abonelik ve son 20 teslimat
PUT/api/v1/webhooks/:idYazma200; güncellenmiş abonelik
DELETE/api/v1/webhooks/:idYazma200; { deleted: true }
POST/api/v1/webhooks/:id/testYazma201; { deliveryId }
POST/api/v1/webhooks/:id/rotate-secretYazma201; abonelik, secret, rotated: true, revealedOnce: true
GET/api/v1/webhooks/:id/deliveriesOkuma200; { 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

AlanOluşturma (POST)Güncelleme (PUT)
urlZorunlu metin; protokollü URL, en fazla 2048 karakterİsteğe bağlı; aynı doğrulama
eventsZorunlu 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
statusOluş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_REGULATIONYeni mevzuat bildirimi
REGULATION_UPDATEDMevzuat güncelleme bildirimi
REGULATION_CLASSIFICATION_COMPLETEDTerminal sektör sınıflandırması bildirimi
ACTION_DEADLINE_APPROACHINGAksiyon vadesinin yaklaşması
IMPACT_ASSESSMENT_CREATEDEtki analizi oluşturulması
QUALITY_SLA_BREACHKalite SLA ihlali bildirimi
VERIFICATION_COMPLETEDDoğrulama çalışmasının tamamlanması
VERIFICATION_REVIEW_REQUIREDDoğrulama için inceleme gereksinimi
BOARD_REPORT_READYYönetim kurulu raporunun hazır olması
EVIDENCE_PACK_READYKanıt paketinin hazır olması
ARTICLE_DIFF_CREATEDMadde 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ıkDeğer / hesaplama
Content-Typeapplication/json
X-Webhook-Signature-V2t=<unix saniye>,v1=<hex>; HMAC SHA-256 girdisi "<t>." + ham gövde
X-Webhook-TimestampUnix saniye cinsinden gönderim zamanı
X-Webhook-Signaturesha256=<hex>; yalnız ham gövde üzerinden eski HMAC SHA-256 imzası
X-Webhook-EventOlay türü
X-Webhook-Event-VersionOlay sürümü; mevcut göndericilerde 1
X-Webhook-Delivery-IdTeslimat kimliği
X-Webhook-Idempotency-KeyAlıcıda tekrar işlemeyi önlemek için saklanan anahtar
X-Webhook-AttemptBirden 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 durumuAnlam
400Geçersiz URL, olay, DTO alanı veya teslimat sayfalaması
401JWT veya API anahtarı eksik/geçersiz, anahtar süresi dolmuş veya iptal edilmiş
402JWT oturumunun aboneliği ürün erişimine kapalı veya bulunamıyor
403ADMIN rolü, sayfa/özellik izni, organizasyon erişimi, CSRF veya abonelik limiti denetimi başarısız
404Abonelik yok, silinmiş veya organizasyon kapsamında değil
429İstek hızı aşıldı; Retry-After ile tekrar zamanı
503Anahtarlı 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.