Olayları dinleyin

Mesaj teslim durumları, gelen mesajlar, Apsilo AI analizleri, kişi değişiklikleri, kampanya ve anket olaylarını kendi sunucunuzda anında alın — yoklamaya (polling) gerek kalmaz.

Kurulum

Panelde Ayarlar → API ve Webhook’lar → Webhook’lar bölümünden bir uç nokta ekleyin: HTTPS adresi ve dinlemek istediğiniz olaylar. Gizli anahtar (whsec_…) yalnızca oluşturma anında gösterilir. Firma başına en fazla 20 uç nokta tanımlanabilir; uç noktayı webhooks:manage kapsamıyla API üzerinden de yönetebilirsiniz.

Olaylar

Toplam 23 olay türü. Yalnızca ihtiyacınız olanlara abone olun; yeni türler zamanla eklenir.

Apsilo AI: message.analyzed

Apsilo AI gelen bir mesajı, yorumu veya şikayeti analiz ettiğinde gönderilir. Mesajın kendisi message.received / comment.received ile ayrıca bildirilir; analiz arka planda üretildiği için bu olay onlardan kısa süre sonra gelir. data.analysis, mesaj nesnesindeki analysis alanıyla aynı yapıdadır.

{
  "type": "message.analyzed",
  "data": {
    "messageId": "3c9a7f42-6c7d-4a5e-9d11-0c2f4b8a77e1",
    "conversationId": "b71e…",
    "contactId": "4d20…",
    "channel": "instagram",
    "type": "comment",
    "analysis": {
      "kind": "inbound",
      "sentiment": "negative",
      "intent": "complaint",
      "urgency": 4,
      "flags": ["profanity"],
      "categories": {},
      "autoHidden": false,
      "analyzedAt": "2026-09-17T09:15:02.000Z"
    },
    "messageCreatedAt": "2026-09-17T09:15:00.000Z",
    "at": "2026-09-17T09:15:02.000Z"
  }
}

Olay gövdesi

Tüm olaylar aynı zarfla gelir. id olayın benzersiz kimliğidir: tekrar teslimlerde aynı kalır, bu yüzden tekilleştirmeyi onunla yapın.

apiVersion (2026-09-14) yük şeması değiştiğinde artar; data alanının içeriği olay türüne göre değişir.

Olayların birbirini izleyen sırada geleceğini varsaymayın; sıralama için createdAt alanını kullanın.

{
  "id": "01J9Z5K2F3R7QW8N",
  "type": "message.delivered",
  "apiVersion": "2026-09-14",
  "createdAt": "2026-09-17T09:15:00.000Z",
  "tenantId": "8f1c…",
  "data": {
    "messageId": "3c9a…",
    "channel": "whatsapp",
    "conversationId": "b71e…",
    "contactId": "4d20…",
    "status": "delivered",
    "occurredAt": "2026-09-17T09:14:59.000Z"
  }
}

POST /apsilo/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Apsilo-Webhooks/1.0
Apsilo-Event: message.delivered
Apsilo-Delivery: 6f0c…
Apsilo-Webhook-Id: 9a71…
Apsilo-Signature: t=1791964800,v1=64479091c82c3237…

İmza doğrulama

İmza ham gövde üzerinden hesaplanır: HMAC-SHA256(secret, "<t>.<ham gövde>"). Gövdeyi JSON’a çevirmeden önce doğrulayın.

Zaman damgası toleransı 5 dakikadır; daha eski istekleri reddedin (tekrar oynatma koruması). Karşılaştırmayı sabit zamanlı bir fonksiyonla yapın.

import crypto from "node:crypto";
 
// Ham gövde gerekir: express.raw({ type: "application/json" })
app.post("/apsilo/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Apsilo-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
 
  const t = Number(parts.t);
  const fresh = Number.isFinite(t) && Math.abs(Date.now() / 1000 - t) <= 300;
  if (!fresh) return res.sendStatus(400);
 
  const expected = crypto
    .createHmac("sha256", process.env.APSILO_WEBHOOK_SECRET)
    .update(t + "." + req.body)
    .digest("hex");
 
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
  if (!ok) return res.sendStatus(401);
 
  const event = JSON.parse(req.body.toString("utf8"));
  enqueue(event); // event.id ile tekilleştirin
  res.sendStatus(200);
});

$header = $_SERVER['HTTP_APSILO_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts);
 
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $parts['t'] . '.' . $raw, getenv('APSILO_WEBHOOK_SECRET'));
 
$fresh = abs(time() - (int) ($parts['t'] ?? 0)) <= 300;
if (!$fresh || !hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(401);
    exit;
}
 
$event = json_decode($raw, true);
http_response_code(200);

Yeniden deneme ve otomatik devre dışı bırakma

2xx dışındaki yanıtlar ve zaman aşımları başarısız sayılır. Teslim artan aralıklarla tekrarlanır:

Art arda 50 başarısız teslimde uç nokta otomatik devre dışı kalır ve firma yöneticisine bildirim gider; panelden yeniden etkinleştirdiğinizde bekleyen teslimler gönderilir. Panelde her teslimin isteği, yanıtı ve süresi görünür, tek tek yeniden gönderebilirsiniz.

İyi uygulamalar