Olaylar ve Webhook’lar

Alarm ve sevkiyat olaylarını öğrenmek için API’yi sürekli sorgulamanız (polling) gerekmez. Bir HTTPS adresi tanımlarsınız, olay gerçekleştiğinde Frigolive o adrese imzalı bir POST isteği gönderir.

Webhook’lar mobil uygulamanın doğrudan dinlemesi için değil, müşterinin güvenli backend servisine olay iletmek için tasarlanmıştır.

Kurulum

Uç noktalar Frigolive panelinde Ayarlar → Webhook’lar ekranından yönetilir. Adres kaydedildiğinde bir imza sırrı üretilir ve yalnızca o anda bir kez gösterilir. Bu sırrı alıcı servisinizin secret kasasına kaydedin.

Aynı ekrandan test olayı gönderebilir, son 100 teslimat denemesini yanıt kodu ve hata mesajıyla birlikte görebilirsiniz.

Yayınlanan olaylar

Her uç nokta yalnızca abone olduğu olayları alır. Yeni olay türü eklenmesi geriye uyumludur; bilmediğiniz bir type gelirse sessizce yok sayın.

İstek biçimi

POST /sizin-alici-adresiniz HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: Frigolive-Webhooks/1.0
X-Frigolive-Event: alarm.created
X-Frigolive-Event-ID: 7126f58a-77c7-4d50-aa87-d1dd99297713
X-Frigolive-Delivery-ID: 0fbc2c15-10ab-4b75-a59e-043b23614b60
X-Frigolive-Timestamp: 1785312000
X-Frigolive-Signature: v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
 
{
  "id": "7126f58a-77c7-4d50-aa87-d1dd99297713",
  "type": "alarm.created",
  "created_at": "2026-07-27T11:42:00Z",
  "data": {
    "id": "0fbc2c15-10ab-4b75-a59e-043b23614b60",
    "device_id": "a6532895-026f-4dad-9f89-432a33e93bc0",
    "shipment_id": 481,
    "type": "TEMPERATURE",
    "severity": "WARNING",
    "source": "THRESHOLD",
    "message": "Sıcaklık üst eşiği aşıldı.",
    "resolved": false,
    "created_at": "2026-07-27T11:42:00Z",
    "resolved_at": null
  }
}

İmzayı doğrulayın

İmzalanan metin "{timestamp}.{ham gövde}" biçimindedir ve HMAC-SHA256 ile imzalanır. Ham gövdeyi kullanın — JSON’u ayrıştırıp yeniden serileştirirseniz baytlar değişir ve imza tutmaz.

import hashlib
import hmac
import time
 
TOLERANCE_SECONDS = 300  # 5 dakika
 
def verify(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    # 1) Zaman penceresi: yakalanmış eski bir isteğin tekrar oynatılmasını engeller.
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
 
    # 2) İmzayı yeniden üret.
    signed = f"{timestamp}.".encode() + raw_body
    expected = "v1=" + hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()
 
    # 3) Sabit zamanlı karşılaştır: baytları tek tek sızdırmamak için.
    return hmac.compare_digest(expected, signature)

Node.js karşılığı:

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verify(rawBody: Buffer, timestamp: string, signature: string, secret: string) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
 
  const expected =
    "v1=" +
    createHmac("sha256", secret)
      .update(Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]))
      .digest("hex");
 
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Yanıt vermeniz gereken şey

10 saniye içinde 2xx döndürün. Gövde okunmaz, boş yanıt yeterlidir.

Ağır işi senkron yapmayın: olayı kendi kuyruğunuza yazıp hemen 200 dönün. Yavaş yanıt zaman aşımına düşer ve gereksiz tekrar teslimata yol açar.

Tekrar denemeler ve idempotency

Arka arkaya 20 başarısız teslimattan sonra uç nokta otomatik olarak devre dışı bırakılır ve panelde uyarı görünür. Adresi düzelttikten sonra aynı ekrandan yeniden etkinleştirirsiniz.

Sır döndürme

Panelden yeni bir imza sırrı üretebilirsiniz. Yeni sır üretildiği anda geçerli olur; eski sırla imzalanmış bekleyen teslimat yoksa kesinti yaşanmaz. Kesintiyi tamamen ortadan kaldırmak için alıcınızı geçiş süresince iki sırrı da kabul edecek biçimde yazabilirsiniz.

Güvenlik kontrol listesi

1. Yalnızca https:// adres kullanın — panel http:// kabul etmez.
2. Her istekte imzayı doğrulayın; doğrulanmayan isteği işlemeyin.
3. Timestamp toleransını 5 dakikayı aşmayacak biçimde uygulayın.
4. İmza sırrını secret kasasında saklayın, koda veya loga yazmayın.
5. X-Frigolive-Event-ID ile tekrarları eleyin.
6. Alıcı adresinizi tahmin edilmesi zor bir yol altında yayınlayın.