Event Streams: webhook gövde şablonu ve olay filtresi

Event Streams, giden webhook'ların (docs/webhooks.md) gövdesini alıcının beklediği biçime dönüştürmenizi ve yalnızca ilgilendiğiniz olayları almanızı sağlar (docs/adr/0030-event-streams-ve-veri-ambari.md). Dashboard'da Geliştirici → Webhooks → endpoint formu → Event Streams bölümünden veya API'de body_template, body_content_type, filters alanlarıyla ayarlanır.

Gövde şablonu (Liquid)Bağlantıyı kopyala

Şablon boşsa standart gövde gönderilir. Şablonda olay event adıyla kullanılır:

application/json (varsayılan): değişken çıktıları otomatik olarak JSON dize içeriği olarak kaçışlanır, bu yüzden tırnak içinde güvenle kullanılır. Bir nesneyi olduğu gibi gömmek için json ve raw filtrelerini birlikte kullanın. Çıktı geçerli JSON olmalıdır.

{
  "text": "{{ event.type }} — kampanya {{ event.data.campaign_id }}",
  "user": "{{ event.data.user.external_id }}",
  "event": {{ event | json | raw }}
}

text/plain: kaçış yapılmaz, çıktı olduğu gibi gönderilir (Content-Type: text/plain; charset=utf-8).

{{ event.type }} {{ event.data.delivery_id }} {{ event.created_at }}

Kurallar:

• Şablon en fazla 64 KB, render çıktısı en fazla 1 MB. include/render/layout etiketleri ve bilinmeyen filtreler kullanılamaz; render süresi ve belleği sınırlıdır.
• Batch modunda (yüksek hacimli delivery.* olayları) şablon her olay için ayrı render edilir: JSON türünde sonuçlar bir dizi ([…, …]), metin türünde satırlar olarak gönderilir.
• İmza (Pushizo-Signature) gönderilen gövde üzerinden hesaplanır; doğrulama değişmez.
• Şablon hatası (render hatası, geçersiz JSON, aşırı büyük çıktı) teslimde istek gönderilmeden kalıcı hata olarak kaydedilir (template_invalid_json: … gibi açık hata metni, teslim geçmişinde görünür). Şablonu düzeltip Yeniden gönder ile tekrar iletebilirsiniz. Kayıt sırasında sözdizimi hatası olan şablon reddedilir.

Olay filtresiBağlantıyı kopyala

Filtre yoksa abone olunan tüm olaylar gönderilir. Koşullar all (hepsi) veya any (herhangi biri) ile birleşir; en fazla 20 koşul.

Operatörler: eq, neq, in, not_in (değer listesi), starts_with, contains (metinde alt dize, dizide eleman), exists, not_exists. Karşılaştırma metin olarak yapılır (120 ile "120" eşittir).

{
  "match": "all",
  "conditions": [
    { "field": "campaign_id", "op": "eq", "value": "cmp_01JABC…" },
    { "field": "channel", "op": "in", "value": ["ios_push", "android_push"] }
  ]
}

Filtre olay üretildiği anda uygulanır: eşleşmeyen olaylar için teslim kaydı oluşmaz. Filtreyi sonradan değiştirirseniz henüz gönderilmemiş eşleşmeyen teslimler filtered_out hatasıyla kapatılır. event.received için mevcut olay adı filtresi (event_filters.event_names) zorunlu olmaya devam eder ve Event Streams filtresiyle birlikte uygulanır.

ÖnizlemeBağlantıyı kopyala

Kaydetmeden önce sonucu görün; istek gönderilmez:

curl -X POST "$API/v1/apps/$APP_ID/webhooks/preview" -H "Authorization: Bearer $HS_KEY" -H 'content-type: application/json' -d '{
  "event_type": "delivery.clicked",
  "data": { "campaign_id": "cmp_01JABC…", "channel": "ios_push" },
  "body_template": "{\"text\": \"{{ event.type }}\"}",
  "filters": { "match": "all", "conditions": [{ "field": "campaign_id", "op": "eq", "value": "cmp_01JABC…" }] }
}'

Yanıt: matched (filtreden geçer mi), failed_conditions, body (render çıktısı), content_type ve hata varsa error.code (render_error, invalid_json, body_too_large). data verilmezse olay türünün örnek verisi kullanılır.