Web Kancaları
Kendi sistemlerinizi Flash olaylarına abone edin. İlgilendiğiniz olaylar için bir HTTPS uç noktası kaydedin ve Flash her biri tetiklendiği anda imzalı, ince bir yük sunar — sorgulama yok, gece dışa aktarma yok. İmzalar Standart Webhooks spesifikasyonuna uygundur, teslimatlar geri çekilme ile yeniden denenir ve her deneme kaydedilir.
Bir uç noktayı kaydedin
webhooks:manage kapsamını tutan bir Bearer fl_live_ anahtarına sahip bir webhook uç noktası oluşturun. Bir HTTPS url ve oraya iletilmesini istediğiniz eventTypes listesini gönderin. döndürülür ve bir daha asla döndürülmez — güvenli bir şekilde saklayın; her teslimatı doğrulamak için buna ihtiyacınız var.
curl -X POST https://flash.socialhub.ai/api/v2/webhooks \
-H "Authorization: Bearer fl_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.your-app.com/flash",
"description": "prod ingest",
"eventTypes": ["member.created", "loyalty.tier_upgraded"]
}'
# 201 Created
# {
# "data": {
# "id": "whe_...",
# "url": "https://hooks.your-app.com/flash",
# "eventTypes": ["member.created", "loyalty.tier_upgraded"],
# "status": "active",
# "secret": "whsec_..." <-- shown ONCE, store it now
# }
# }Uç noktaları daha sonra GET /api/v2/webhooks (liste, gizli bilgi yok), PATCH /api/v2/webhooks/{id} (URL'yi / olayları / durumu değiştirin veya gizli bilgiyi değiştirmek için { "action": "rotate_secret" } gönderin) ve DELETE /api/v2/webhooks/{id} ile yönetin. Ayrıca Ayarlar → Web Kancaları bölümünden kayıt olabilir, test ping'i gönderebilir ve teslimatları tekrar oynatabilirsiniz.
Etkinlik kataloğu
API'a hangi etkinliklere abone olabileceğinizi sorun. Katalog, canlı otomasyon tetikleyicisi doğruluk kaynağından türetilmiştir, bu nedenle yalnızca bugün gerçekten tetiklenen etkinlikleri listeler; bunlar yaşam döngüsü aşamasına göre (edinme, etkileşim, sadakat, elde tutma, ticaret, savunuculuk) gruplandırılmıştır ve her birinin etkinlik anahtarı, açıklaması ve örnek yükü bulunur. Yanıt ayrıca paylaşılan yük zarfını ve imza başlıklarını da belgeler.
curl https://flash.socialhub.ai/api/v2/events/catalog \
-H "Authorization: Bearer fl_live_..."
# { "data": { "events": [
# { "event": "member.created", "label": "Member created",
# "stage": "acquisition", "examplePayload": { ... } },
# { "event": "loyalty.tier_upgraded", "label": "Tier upgraded",
# "stage": "loyalty", "examplePayload": { ... } },
# ...
# ],
# "payload": { "schema": { ... }, "headers": { ... } }
# } }Abone olduğunuzda bir etkinliğin event anahtarını doğrudan eventTypes array'a yerleştirin. webhooks:manage kapsamını gerektirir.
İnce, kişisel bilgi içermeyen bir veri yükü
Her teslimat aynı küçük zarfı içerir: sabit bir id, olay type, bir created_at timestamp ve kompakt bir data bloğu. Yük asla kişisel veri içermez — e-posta, isim, telefon veya adres yok. Üyenin bilgilerine ihtiyaç duyduğunuzda, member_ref kullanarak kimlik doğrulaması yapılmış API üzerinden bunları geri alın. Bu, kişisel tanımlayıcı bilgilerin üye kaydında kalmasını ve web kancası günlüklerinizden uzak tutulmasını sağlar.
POST https://hooks.your-app.com/flash
webhook-id: evt_a1b2c3... # stable across retries — dedupe on this
webhook-timestamp: 1767225600 # unix seconds
webhook-signature: v1,K5x0mF...== # base64 HMAC-SHA256 (may be space-separated during rotation)
Content-Type: application/json
{
"id": "evt_a1b2c3...",
"type": "loyalty.tier_upgraded",
"created_at": "2026-01-01T00:00:00.000Z",
"data": {
"resource_id": "mbr_...",
"member_ref": "mbr_...", // opaque member id — fetch PII via the API
"tier": "Gold", // present on loyalty / tier events
"amount_band": "100-500" // coarse band on commerce events — never the exact amount
}
}Her imzayı doğrulayın
Flash, uç noktanızın whsec_ gizli anahtarını kullanarak her teslimatı Standart Web Kancaları (HMAC-SHA256) ile imzalar. İmzayı {webhook-id}.{webhook-timestamp}.{body} üzerinden yeniden hesaplayın ve sabit sürede webhook-signature başlığıyla karşılaştırın. Eşleşmeyen her şeyi reddedin ve tekrar oynatmalara karşı savunmak için çok eski olan bir webhook-timestamp'ü reddedin. İmza anahtarı, spesifikasyona göre whsec_ önekinden sonraki gizli anahtarın base64 kod çözülmüş baytlarıdır. Gizli anahtar döndürme sırasında, başlık birden fazla boşlukla ayrılmış v1,… değeri taşır; herhangi bir eşleşme varsa teslimatı kabul edin.
import crypto from "node:crypto";
// req.body must be the RAW, unparsed request body string.
function verifyFlashWebhook(headers, rawBody, whsec) {
const id = headers["webhook-id"];
const ts = headers["webhook-timestamp"];
const sigHeader = headers["webhook-signature"]; // "v1,<b64> v1,<b64> ..."
// reject stale deliveries (5 min tolerance)
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(whsec.replace(/^whsec_/, ""), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(`${id}.${ts}.${rawBody}`)
.digest("base64");
return sigHeader
.split(" ")
.map((p) => p.split(",")[1])
.some((sig) =>
sig &&
sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
);
}Tekrar denemeler, idempotansiyel ve teslimat günlüğü
2xx'i hızla geri döndürün
Herhangi bir 2xx ile onaylayın ve işinizi eşzamansız olarak yapın. Bir 429, bir 5xx, bir zaman aşımı veya bağlantı hatası yeniden denenebilir olarak kabul edilir.
Geri çekilme ile otomatik yeniden deneme
Tekrar denenebilir hatalar, üstel, tam titreşimli geri çekilme ile tekrar denenir. Bir 3xx veya 429 olmayan bir 4xx kalıcı bir hata olarak kabul edilir ve tekrar denenmez.
webhook-id ile tekilleştirme
id, tekrarlanan denemelerde aynıdır, bu nedenle en az bir kez teslimat güvenlidir: tekrarlanan bir webhook-id'i zaten işlenmiş olarak kabul edin.
Teslimat günlüğü ve tekrar oynatma
Her deneme kaydedilir. Yeniden denemeler tükendiğinde teslimat başarısız olarak işaretlenir; Ayarlar → Web Kancaları bölümünden teslimatları inceleyebilir ve tekrar oynatabilirsiniz.