Webhook Abonelikleri API

Webhook yönetim endpointleri API key ile değil, authenticated admin session JWT ile çalışır. Guard zinciri JwtAuthGuard + RolesGuard + settings permission şeklindedir; role ADMIN değilse işlem 403 döner.

Receiver tarafındaki HMAC, retry ve idempotency ayrıntıları için Webhook Akışı sayfasını kullanın. İmza doğrulaması her zaman raw request body üzerinden yapılır; parse edilmiş JSON’u yeniden stringify etmek imzayı geçersiz kılar.

Alan	Değer
Auth	Bearer JWT session
Role	`ADMIN`
Permission	`settings:read` veya `settings:write`
Plan	Webhooks entitlement açık olmalı

Endpoints

Method	Path	Body
`GET`	`/api/v1/webhooks`	Yok
`POST`	`/api/v1/webhooks`	`url`, `events`, `description?`, `includeChildOrgEvents?`
`GET`	`/api/v1/webhooks/:id`	Yok
`PUT`	`/api/v1/webhooks/:id`	Partial update DTO
`DELETE`	`/api/v1/webhooks/:id`	Yok
`POST`	`/api/v1/webhooks/:id/test`	Yok
`POST`	`/api/v1/webhooks/:id/rotate-secret`	Yok
`GET`	`/api/v1/webhooks/:id/deliveries`	`page`, `limit` query

Create Body


{
  "url": "https://example.com/mevzuatradar/webhook",
  "events": ["NEW_REGULATION"],
  "description": "GRC production receiver",
  "includeChildOrgEvents": false
}

Event Kataloğu

Event değerleri shared WebhookEventType sözleşmesinden gelir. Receiver tarafında bilinmeyen event sessizce kabul edilmez; önce durable kuyruğa alınır ve desteklenen event kataloğuna göre işlenir.

Event	Açıklama
`NEW_REGULATION`	Yeni mevzuat veya resmi kaynak dokümanı bulundu
`REGULATION_UPDATED`	Mevzuat kaydında doğrulanmış güncelleme oluştu
`REGULATION_CLASSIFICATION_COMPLETED`	Mevzuatın güncel sektör eşleştirmesi kabul edildi
`ACTION_DEADLINE_APPROACHING`	Aksiyon son tarihi yaklaşıyor
`IMPACT_ASSESSMENT_CREATED`	Etki analizi üretildi
`QUALITY_SLA_BREACH`	Kalite SLA ihlali oluştu
`VERIFICATION_COMPLETED`	Doğrulama koşusu tamamlandı
`VERIFICATION_REVIEW_REQUIRED`	Doğrulama manuel inceleme gerektiriyor
`BOARD_REPORT_READY`	Yönetim kurulu raporu hazır
`EVIDENCE_PACK_READY`	Kanıt paketi hazır
`ARTICLE_DIFF_CREATED`	Madde farkı oluşturuldu

Sektör eşleştirmesi tamamlandı

REGULATION_CLASSIFICATION_COMPLETED, yalnız terminal sonuçlar için gönderilir: kabul edilmiş (ACCEPTED) eşleştirmeler ve — güncel kabul edilmiş bir sonuç yoksa — nihai sınıflandırılamamış (UNCLASSIFIED) kayıtlar. Hazırlanan (ara durumdaki) ve inceleme gerektiren kayıtlar event üretmez; classificationStatus alanı ACCEPTED, UNCLASSIFIED veya LEGACY_INGRESS olabilir. Geçmiş veri taramalarında müşteri teslimatları kapalıdır.


{
  "event_id": "sector-delivery:01JXYZ",
  "event_version": 1,
  "organization_id": "org_01",
  "classificationRunId": "run_01",
  "classificationStatus": "ACCEPTED",
  "regulationId": "reg_01",
  "sourceCode": "BDDK",
  "sourceType": "BDDK"
}

Receiver, event_id ve X-Webhook-Idempotency-Key değerlerini durable saklamalıdır. classificationRunId aynı mevzuatın daha yeni içerik veya sektör sürümünde yeniden değerlendirilmesini ayırt eder.

Yanıt

Controller yanıtları API envelope ile sarılır. POST /api/v1/webhooks ve POST /api/v1/webhooks/:id/rotate-secret sadece ilk gösterimde secret bilgisini revealed-once mantığıyla döndürür; secret repository veya ticket içine yazılmamalıdır.

Hata Kodları

Status	Anlam
`400`	Geçersiz URL, event veya payload
`401`	JWT eksik/geçersiz
`403`	ADMIN rolü, settings permission veya entitlement yok
`404`	Webhook bulunamadı veya tenant kapsamı dışında
`429`	Rate limit aşıldı

Örnekler

curl -s -X POST "https://api.mevzuatradar.com/api/v1/webhooks" \
-H "authorization: Bearer $MEVZUATRADAR_JWT" \
-H "content-type: application/json" \
-d '{"url":"https://example.com/mevzuatradar/webhook","events":["NEW_REGULATION"],"includeChildOrgEvents":false}'