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
| Olay | Ne zaman |
|---|---|
message.received | Müşteriden yeni mesaj geldiğinde |
message.sent | AI, temsilci, kampanya veya API mesaj gönderdiğinde |
conversation.handoff | Sohbet insana devredildiğinde |
contact.created | Bota ilk kez yazan kişi kaydedildiğinde |
contact.consent_changed | Kişi kampanya/bildirim iznini açtığında veya kapattığında (STOP, panel, API, engelleme) |
campaign.completed | Kampanya gönderimi bittiğinde |
post.published | İçerik takvimindeki gönderi kanala veya gruba gönderildiğinde |
miniapp.submission | Bir Mini App formu veya sipariş talebi gönderildiğinde |
miniapp.order_updated | Bir 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
{
"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ık | Anlamı |
|---|---|
X-Hiboty-Event | Olay adı |
X-Hiboty-Delivery | Teslim 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-Signature | sha256= 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-Deliveryile yinelenenleri ayıklayın. - Teslim sırası garanti edilmez;
created_atalanı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"