Geliştiriciler

Giden webhook'lar

Mesaj, kişi, kampanya ve sipariş olaylarını kendi sisteminize alın.

Kurulum

Ayarlar → Webhook'lar bölümünden ya da createWebhook ile HTTPS uç noktanızı kaydedin; seçtiğiniz olaylar JSON olarak POST edilir. Organizasyon başına en fazla 10 webhook açılır. Her webhook'un kendi imza anahtarı (whsec_…) vardır ve yalnız oluştururken gösterilir. localhost ve özel ağ adresleri kaydedilemez.

Olaylar

OlayNe zaman
message.receivedMüşteriden yeni mesaj geldiğinde
message.sentAI, temsilci, kampanya veya API mesaj gönderdiğinde
conversation.handoffSohbet insana devredildiğinde
contact.createdBota ilk kez yazan kişi kaydedildiğinde
contact.consent_changedKişi kampanya/bildirim iznini açtığında veya kapattığında (STOP, panel, API, engelleme)
campaign.completedKampanya gönderimi bittiğinde
post.publishedİçerik takvimindeki gönderi kanala veya gruba gönderildiğinde
miniapp.submissionBir Mini App formu veya sipariş talebi gönderildiğinde
miniapp.order_updatedBir Mini App siparişinin durumu panelden ya da API ile değiştirildiğinde

ping olayı abone olunmaz: panelden ya da testWebhook ile gönderilen test olayıdır.

Örnek yük ve başlıklar

JSON
{
  "id": "5b1c0d8e-6c1f-4f0a-9a57-2b7d8e1f4c33",
  "event": "message.received",
  "created_at": "2026-11-06T09:00:00.000Z",
  "organization_id": "…",
  "data": {
    "message": { "id": "…", "body": "Merhaba, fiyat?", "created_at": "…" },
    "conversation": { "id": "…", "status": "open" },
    "contact": { "id": "…", "channel": "telegram", "external_id": "123456789", "name": "Ayşe" },
    "bot": { "id": "…", "name": "Satış Asistanı", "channel": "telegram" }
  }
}
BaşlıkAnlamı
X-Hiboty-EventOlay adı
X-Hiboty-DeliveryTeslim kimliği; yeniden denemelerde aynı kalır, çift işlemeyi önlemek için saklayın
X-Hiboty-Timestampİmzanın üretildiği an (Unix saniye)
X-Hiboty-Signaturesha256= ve ardından HMAC-SHA256(secret, timestamp + "." + gövde) onaltılık değeri

İmza doğrulama

Her isteği işlemeden önce doğrulayın. 5 dakikadan eski istekleri reddedin (tekrar saldırısı).

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

export function verifyHibotySignature(headers, rawBody, secret) {
  const timestamp = headers["x-hiboty-timestamp"];
  const signature = headers["x-hiboty-signature"] ?? ""; // "sha256=…"
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Gövdeyi ham (parse edilmemiş) haliyle imzalayın; JSON yeniden serileştirilirse imza tutmaz. Uç noktanız 10 saniye içinde 2xx döndürmeli; ağır işleri kuyruğa atın.

Alıcı örneği

Express ve Flask ile en küçük alıcı: ham gövdeyi okur, imzayı doğrular, 2xx döner. Bu örnekler için express ya da flask paketi gerekir.

import express from "express";
import { verifyHibotySignature } from "./verify.mjs";

const app = express();

// Gövde ham (Buffer) okunur: JSON yeniden serileştirilirse imza tutmaz.
app.post("/hiboty-webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyHibotySignature(req.headers, req.body.toString("utf8"), process.env.HIBOTY_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  console.log(req.headers["x-hiboty-delivery"], event.event);
  res.sendStatus(200);
});

app.listen(3000);

Yeniden deneme ve kapanma

2xx dışı yanıtlar 1 dk, 5 dk, 30 dk, 2 sa, 12 sa sonra yeniden denenir. Ardışık 50 başarısız teslimde webhook kapanır (active: false); panelden ya da POST /api/v1/webhooks/{id}/enable ile yeniden açılır.

  • Başarılı bir teslim ardışık hata sayacını sıfırlar; webhook'u yeniden açmak da sayacı sıfırlar.
  • Aynı olay yeniden gönderilebilir: X-Hiboty-Delivery ile yinelenenleri ayıklayın.
  • Teslim sırası garanti edilmez; created_at alanına bakın.

Teslimleri izleme

Teslim geçmişi durum, deneme sayısı ve hatayı gösterir; olayın içeriği kişisel veri taşıyabildiği için dönmez.

curl "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/deliveries?limit=20" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/enable" -H "Authorization: Bearer $HIBOTY_API_KEY"