API & Webhooks

Callert'e dış dünyadan veri göndermek için tek bir Ingest Endpoint kullanılır.

Ingest Endpoint

POST https://notification.callert.app/ingest/i/:integrationKey

:integrationKey değerini dashboard'daki Integration detay sayfasından alabilirsiniz.

Güvenlik (zorunlu): Gizli anahtar yalnızca X-Callert-Token header ile gönderilmeli; URL içinde asla taşınmaz. Alternatif olarak X-Timestamp ve X-Signature (HMAC-SHA256) kullanılabilir.

Payload Formatı

Callert, esnek bir JSON yapısını kabul eder. En azından bir başlık (title) veya mesaj alanı olmalıdır. Callert otomatik olarak birçok formatı (Prometheus Alertmanager, Uptime Kuma) tanır. "Generic Webhook" için önerilen minimal format şöyledir:

{ "title": "Database Connection Failed", "message": "Connection timed out after 30s", "status": "DOWN", "severity": "critical", "dedupe_key": "db-conn-fail-01", "tags": { "env": "production", "service": "payment-api" } }

Alan	Tip	Zorunlu?	Açıklama
title	string	Evet*	Alarmın başlığı.
message	string	Hayır	Kısa açıklama/metin. Alternatif olarak `description` kullanılabilir.
status	enum	Evet*	`DOWN`, `UP`, veya `RESOLVED`. `UP`/`RESOLVED` açık incident'i kapatır.
severity	enum	Hayır	`info`, `warning`, `critical`. Default: `warning`.
dedupe_key	string	Hayır	Tekrarlayan alarmları gruplamak için anahtar. Aynı anahtar yeni incident açmaz, event ekler.
tags	object	Hayır	Rule engine için key/value etiketler.

Status Page API

Bir projenin public status sayfası için özet endpoint.

GET https://api.callert.app/status/p/:publicKey

Notification Flow (Sekans Diyagramı)

Aşağıdaki metinsel sekans diyagramı, bir alarmın Callert'e gelişinden dashboard'daki sinyallere kadar olan temel teknik akışı özetler. Bu akış; API, kural motoru, kuyruklar, provider entegrasyonları ve tenant seviyesindeki sinyalleri tek bir yerde görmenizi sağlar.

Monitor / Alert Source | | 1) HTTP POST /ingest/i/:integrationKey v Callert API (Ingest Controller) | | 2) Payload normalizasyonu, tenant + project çözümleme v Rule Engine | | 3) Kuralların değerlendirilmesi (seviyeler, etiketler, bakım, sessiz saatler) | 4) Hangi kullanıcıların hangi kanal üzerinden bilgileneceğine karar v BullMQ Queues | | 5) CALL / SMS / EMAIL işler kuyruklara yazılır v Notification Workers | | 6) Provider API çağrıları (operatörler) v Providers (Telephony / SMS / Email) | | 7) Callback (Webhook) ile başarı / hata dönüşü v Callback Endpoint | | 8) NotificationAttempt güncellemesi | 9) firstIncidentAt / firstFailedNotificationAt / firstSkippedDecisionAt sinyallerinin güncellenmesi v Tenant & Incident State | | 10) Dashboard: Incident detay ekranı, "Teslimat Kararları" paneli | 11) Dashboard: İlk incident / ilk provider hatası / ilk atlanan bildirim toast'ları v Kullanıcı (On-call / Ekip)

Rate Limits

Global API istekleri kullanıcı başına 5 dakikada en fazla 300 istek ile sınırlandırılır. Ingest endpoint'leri entegrasyon başına dakikada 60 istek ve aynı entegrasyon + IP çifti için dakikada 10 istek sınırına sahiptir. Public status page endpoint'i (GET /status/p/:publicKey) aynı IP için dakikada en fazla 30 istek ve dakikada en fazla 5 farklı publicKey denemesine izin verir. Limit aşıldığında istek 429 Too Many Requests veya {"status":"rate_limited"} olarak yanıtlanabilir.