Ana içeriğe geç

iletiMerkezi Webhooks

Webhook, send-sms ile gönderdiğiniz mesajların teslimat durumunu sunucunuza gerçek zamanlı olarak iletir. iletiMerkezi panelinden URL tanımlarsınız; her bir mesajın durum güncellemesinde (kabul, teslim, başarısız) belirttiğiniz URL'ye POST isteği gelir. get-report polling'ine göre daha verimli, daha az gecikmelidir.

Kurulum

  1. panel.iletimerkezi.com → Ayarlar → API → Bildirim Adresi sekmesine gidin.
  2. Webhook URL'sini girin (örn. https://yourdomain.com/api/iletimerkezi/webhook) ve Ekle ile kaydedin.
  3. URL HTTPS olmalı ve dış erişime açık olmalı. iletiMerkezi sunucularından gelen POST isteklerini bu URL üzerinden alacaksınız.

Hesap başına tek webhook URL desteklenir. Birden çok hedefe aynı raporu yönlendirmek istiyorsanız webhook handler'ınızdan kendi tarafınızda fan-out yapın.

Webhook URL'si bir kez tanımlandığında tüm send-sms siparişlerinin teslimat raporları otomatik olarak buraya iletilir; ek bir API çağrısı gerekmez.

İstek

iletiMerkezi her bir mesaj durum güncellemesinde sizin URL'nize aşağıdaki yapıda POST atar:

POST https://yourdomain.com/api/iletimerkezi/webhook
Content-Type: application/json
{
  "report": {
    "id": 1599558518,
    "packet_id": 104525848,
    "status": "accepted",
    "to": "+905XXXXXXXXX",
    "body": "Mesaj metni"
  }
}

Alanlar

  • report.id (integer): Sipariş içindeki tek bir mesajın eşsiz ID'si. Bireysel mesajı tanımlar.
  • report.packet_id (integer): Mesajın ait olduğu siparişin ID'si. send-sms yanıtındaki order.id ile eşleşir; aynı siparişten gelen tüm webhook olayları aynı packet_id'yi taşır.
  • report.status (string): Mesaj durumu (aşağıdaki tabloya bakın).
  • report.to (string): Alıcı numara, +90 prefix'i ile.
  • report.body (string): Gönderilen mesaj metni.

Durum değerleri (report.status)

| Değer | Anlam | |---|---| | accepted | Mesaj kabul edildi, gönderim için kuyruğa alındı | | delivered | Mesaj alıcıya başarıyla iletildi | | undelivered | Mesaj iletilemedi (kapalı hat, kara liste, format vb.) |

get-report numerik kodlar (110, 111, 112) döndürürken webhook string değerler (accepted, delivered, undelivered) gönderir. Tek bir mesajın yaşam döngüsünde tipik olarak önce accepted, ardından delivered ya da undelivered webhook'u gelir.

Yanıt

Webhook isteğine 2xx (örneğin 200 OK) yanıt vermeniz beklenir. 2xx dışı bir yanıt iletiMerkezi tarafının webhook'u "başarısız" olarak işaretlemesine yol açabilir; idempotent kabul ve hızlı 200 dönmek standart pattern'dir.

HTTP/1.1 200 OK
Content-Type: application/json

{"received": true}

Güvenlik

iletiMerkezi webhook'ları şu an HMAC imzası veya X-Signature benzeri bir header göndermez; payload doğrudan report objesidir. Üretimde alıcı tarafında en az bir doğrulama katmanı uygulamak zorundasınız.

Önerilen pattern: URL içinde gizli token. Webhook URL'sini panelde bir token query parametresiyle tanımlayın; handler'ınız bu token'ı sabit bir değerle eşleştirip uyuşmayan istekleri 401 ile reddetsin. Bu, iletiMerkezi DLR'lerini tüketen iç servislerimizde de aynı şekilde uygulanan pattern'dir.

POST https://yourdomain.com/api/iletimerkezi/webhook?token=GIZLI_DEGER
// Handler örneği (Node/Express)
app.post('/api/iletimerkezi/webhook', (req, res) => {
  if (req.query.token !== process.env.WEBHOOK_TOKEN) {
    return res.status(401).end();
  }
  // ... payload işle
  res.status(200).json({ received: true });
});

Ek savunma:

  • Webhook URL'sini paylaşmayın, repo'ya commit etmeyin (yalnızca env var olarak tutun).
  • HTTPS zaten zorunlu — panel HTTP URL'lerini kabul etmez.
  • Şüphe varsa istemcide alınan report.packet_id'yi kendi DB'nizdeki siparişle eşleştirin; eşleşmeyen DLR'leri sessizce yok sayın (aşağıdaki "Multi-app filtering" pitfall'ına bakın).

Native HMAC signature desteği yol haritasında bir aday özelliktir; mevcut sistemde yoktur. URL-token convention'ı bugünün gerçek koruma katmanıdır.

Common Pitfalls

  • Hesabın tüm SMS'leri tek webhook URL'sine düşer (multi-app filtering). Aynı iletiMerkezi hesabını birden fazla uygulama paylaşıyorsa, uygulamanıza ait olmayan DLR'ler de webhook'unuza gelir. Alıcı tarafta report.body içinde uygulamanıza özgü bir marker (örn. kısa link domain'i iim.to/..., bir kampanya tag'i veya sipariş ID prefix'i) arayıp uyuşmayanları 200 OK ile sessizce yok sayın. Yoksa kendi mesajınız sandığınız orphan DLR'leri DB'nize yazarsınız.

    // Pratik örnek: kısa link domain'i marker olarak
if (!report.body.includes('iim.to')) {
  return new Response('OK', { status: 200 });  // bizim değil, sessiz drop
}

  • Aynı report.id birden çok kez gelebilir; idempotent yazın. Operatör retry'leri veya iletiMerkezi sunucu retry'i nedeniyle aynı durum güncellemesi tekrarlanabilir. Pratik pattern: ilk callback'te delivery_received_at + status yazın, sonraki callback'lerde sadece status'u güncelleyin (timestamp dokunulmaz). İdempotency anahtarı: report.id + report.status.

  • packet_id ile send-sms order.id aynıdır. Webhook'ları siparişle eşleştirmek için bu alanı kullanın; aynı siparişten gelen birden çok mesajın webhook'u aynı packet_id'yi taşır.

  • accepted "iletildi" demek değildir. Sadece "kabul edildi, kuyruğa alındı" demek. Gerçek teslim için delivered webhook'u beklenir.

  • Webhook URL'iniz hızlı yanıt vermelidir. Uzun süren işlemleri (DB write, üçüncü parti API çağrısı) arka plan kuyruğuna gönderip webhook handler'da hemen 200 dönün; yoksa iletiMerkezi tarafı timeout görüp retry yapabilir.

  • HTTPS zorunlu. HTTP URL'ler kabul edilmez veya iletilmez (panele girilemez). Lokal geliştirmede ngrok veya cloudflared tunnel kullanılır.

  • Webhook tanımlanmamışsa polling. Webhook URL boşsa teslimat durumu sadece get-report ile çekilebilir. Üretimde webhook tercih edilir; polling'e fallback ekleyebilirsiniz.

Related

Son güncelleme: 2026-04-29 · English version