Webhook — sonucu yazılımınıza bildirme

Onam tamamlandığında eOnam sizin belirlediğiniz adrese bir POST gönderir. Sürekli sorgulama yapmak yerine bunu kullanın: hasta onamı gece yarısı imzalayabilir, sizin yazılımınız o sırada kapalı olabilir — webhook yeniden dener.

Kurulum

Panelden Ayarlar → Webhook ekranından adres tanımlarsınız. Adres HTTPS olmalıdır. Kaydederken üretilen imza anahtarı yalnızca size aittir; isteklerin gerçekten eOnam'dan geldiğini bununla doğrularsınız.

Olaylar

Hangi olayları alacağınızı webhook tanımında seçersiniz; varsayılan consent.completed, consent.rejected, consent.expired.

İstek biçimi

POST https://sizin-sunucunuz/eonam-webhook
Content-Type: application/json
X-eOnam-Event: consent.completed
X-eOnam-Delivery: 4812
X-eOnam-Timestamp: 1788027266
X-eOnam-Signature: sha256=9f31c4b8…

{
  "event":      "consent.completed",
  "created_at": "2026-08-29T00:42:14+03:00",
  "data": {
    "id":           "ons_260829_hm97qdtv9z5m1e15",
    "status":       "completed",
    "external_ref": "ISLEM-2026-8842",
    "patient":      { "name": "Ayşe Yılmaz", "phone": "0555 *** ** 67" },
    "template":     { "code": "implant_onami", "version": 2,
                       "content_sha256": "75282db059a084562c3bf786f0471096…" },
    "document": {
      "sha256":     "63300946b032e0c4…",
      "pdf_url":    "https://eonam.tr/indir.php?…",
      "verify_url": "https://eonam.tr/dogrula.php?u=ons_260829_…"
    },
    "timestamp": { "status": "ok", "time": "2026-08-29 00:42:14",
                    "serial": "07586FE9", "provider": "turktrust" }
  }
}

data, REST'teki onam nesnesinin aynısıdır.

İmza doğrulama

İmza, zaman damgası ile gövdenin nokta ile birleştirilmiş hâlinin HMAC-SHA256 özetidir:

imza = "sha256=" + HMAC-SHA256(timestamp + "." + ham_govde, imza_anahtari)

Zaman damgasının imzaya dahil olmasının sebebi, eski bir isteğin kaydedilip tekrar oynatılmasını (replay) engellemektir.

PHP

$ham   = file_get_contents('php://input');
$zaman = $_SERVER['HTTP_X_EONAM_TIMESTAMP'] ?? '';
$imza  = $_SERVER['HTTP_X_EONAM_SIGNATURE'] ?? '';

// 5 dakikadan eski istekleri kabul etme
if (abs(time() - (int)$zaman) > 300) {
    http_response_code(400); exit;
}

$beklenen = 'sha256=' . hash_hmac('sha256', $zaman . '.' . $ham, IMZA_ANAHTARI);

// hash_equals: zamanlama saldırısına karşı sabit süreli karşılaştırma
if (!hash_equals($beklenen, $imza)) {
    http_response_code(401); exit;
}

$olay = json_decode($ham, true);
// … kendi kaydınıza işleyin …

http_response_code(200);
echo 'ok';

C#

var ham   = await new StreamReader(Request.Body).ReadToEndAsync();
var zaman = Request.Headers["X-eOnam-Timestamp"].ToString();
var imza  = Request.Headers["X-eOnam-Signature"].ToString();

using var h = new HMACSHA256(Encoding.UTF8.GetBytes(imzaAnahtari));
var hesap = "sha256=" + Convert.ToHexString(
    h.ComputeHash(Encoding.UTF8.GetBytes(zaman + "." + ham))).ToLowerInvariant();

if (!CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(hesap), Encoding.UTF8.GetBytes(imza)))
    return Unauthorized();

Gövdeyi çözmeden önce imzayı doğrulayın ve imzayı ham gövde üzerinden hesaplayın. JSON'u çözüp yeniden oluşturursanız boşluk ve sıralama değişir, imza tutmaz.

Cevap ve yeniden deneme

Sunucunuz 2xx döndürürse teslimat başarılı sayılır. Başka her şey (4xx, 5xx, zaman aşımı, bağlantı hatası) başarısızdır ve yeniden denenir:

Yedi denemeden sonra teslimat başarısız olarak kapatılır ve panelde görünür. Teslimat geçmişini Ayarlar → Webhook ekranından inceleyebilir, tek tek yeniden gönderebilirsiniz.

Uygulama önerileri

• Hızlı cevap verin. Ağır işi kuyruğa alın, webhook isteğine hemen 200 dönün. Uzun süren işlemler zaman aşımına düşer ve gereksiz yere yeniden denenir.
• Aynı olay iki kez gelebilir. Ağ kesintisinde cevabınız bize ulaşmazsa yeniden gönderilir. X-eOnam-Delivery numarasını veya onam id'sini saklayıp mükerrer işlemeyi engelleyin.
• Sıra garantisi yoktur. Olayları geliş sırasına değil, içlerindeki created_at alanına göre değerlendirin.
• İndirme adreslerini saklamayın. pdf_url 24 saatlik imzalı bir bağlantıdır. PDF'i indirip kendi arşivinize koyun veya gerektiğinde REST'ten yeniden alın.
• content_sha256 ve document.sha256 değerlerini kendi kaydınıza yazın. Bir uyuşmazlıkta "hasta şu metni okudu, belge şudur ve değişmemiştir" iddiasının dayanağı bunlardır.

Webhook kuramıyorsanız

Sunucunuz dışarıdan erişilebilir değilse (klinik içi ağ, sabit IP yok), webhook yerine düzenli aralıklarla sorgulayabilirsiniz:

curl -u "$KEY:$SECRET" \
  "https://api.eonam.tr/v1/consents?status=completed&from=2026-08-29"

Dakikada bir sorgulamak yerine 5–10 dakikada bir sorgulamak yeterlidir; istek sınırı anahtar başına dakikada 120'dir.