Webhook'lar

Bir HTTPS endpoint’i kaydet, bir şey olduğunda pon seni çağırsın — polling döngüsü yok, boşa giden istek yok. Webhook’ları my.pon.app → Webhook’lar üzerinden veya API ile yönet.

Topic’ler

Gerçekten ihtiyacın olana abone ol. İsteğe bağlı bir listIds filtresi (en fazla 50, yalnızca kendi listelerin — bilinmeyen id’ler invalidListIds ile 400 döner) teslimatları belirli listelere daraltır.

Kaydet

POST /v3/webhooks

curl -X POST https://api.pon.app/v3/webhooks \
  -H "Authorization: Bearer pon_pat_XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/pon",
        "events": ["item.checked"],
        "listIds": ["LIST_ID"] }'

Yanıt, imzalama gizli anahtarını (whsec_…) içerir — yalnızca bir kez gösterilir. Aynı URL’yi yeniden kaydetmek aboneliği günceller ve gizli anahtarı korur. Hesap başına en fazla 5 webhook.

Teslimatlar

Her teslimat, PON-Event: <topic> ve PON-Signature: sha256=<hmac> header’larıyla bir POST isteğidir:

{ "event": "item.checked", "listId": "6led…", "cursor": 123, "at": "2026-08-09T19:00:00.000Z" }

Teslimatlar best-effort, retry yok — endpoint’in çöktüyse bir sonraki olay (veya senin tarafından bir fetch) seni güncele getirir. Redirect’ler takip edilmez. Tek bir yazmadaki birden çok eşleşen değişiklik, abone olunan topic başına tek teslimatta birleşir.

İmzayı doğrula

Gizli anahtarınla ham istek gövdesi üzerinden bir HMAC-SHA256 hesapla ve — sabit zamanlı olarak — header ile karşılaştır:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    header.length === expected.length &&
    timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(header, expected)

Circuit breaker

Bir 2xx teslimatı onaylar. Art arda 20 başarısızlıktan sonra (başka her şey, timeout’lar dahil) webhook otomatik olarak duraklatılır (status: paused, pausedReason: auto_failures). Endpoint’ini düzelt, sonra my.pon.app’te veya PATCH /v3/webhooks/{id} ile { "status": "active" } göndererek yeniden etkinleştir — yeniden etkinleştirmek sayacı sıfırlar. Manuel bir test ping’i POST /v3/webhooks/{id}/pings (asla başarısızlık sayılmaz).