Webhooklar

Dasturchi webhooklari hisob hodisalarini serveringizga yuboradi, shuning uchun doim so‘rab turish shart emas. Yetkazish kamida bir marta bajariladi: hodisa takrorlanishi, kechikishi yoki tartibsiz kelishi mumkin.

Endpoint ro‘yxatdan o‘tkazish#

webhooks:write ruxsatli kalit yarating, keyin ochiq HTTPS qabul qiluvchi va kerakli eng kichik hodisalar to‘plamini ro‘yxatdan o‘tkazing.

curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-production-v1" \
  -d '{
    "url": "https://api.example.com/webhooks/make-agent-fast",
    "events": ["lead.created", "conversation.started"]
  }'

URL HTTPS ishlatishi, foydalanuvchi nomi, parol, fragment yoki maxsus port saqlamasligi va faqat ochiq IP manzillarga yechilishi kerak. Yetkazishda redirect kuzatilmaydi.

201 javobi whsec_... imzolash sirini bir marta ko‘rsatadi. Javobni yopishdan oldin uni qabul qiluvchining sirlar boshqaruvchisida saqlang. Keyin endpointlar ro‘yxati URL, hodisalar, holat, oxirgi yetkazish va oxirgi xatoni qaytaradi, ammo sirni emas.

Hodisa turlari#

So‘rov formati#

Make Agent Fast Content-Type: application/json, User-Agent: MakeAgentFast-Webhooks/1.0 va quyidagi sarlavhalar bilan POST yuboradi:

maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256

JSON tanasi barqaror qobiqka ega. data ichidagi maydonlar hodisaga bog‘liq va yangi qo‘shimcha maydonlar olishi mumkin.

{
  "id": "evt_2c34...",
  "type": "lead.created",
  "created_at": "2026-07-16T10:02:46.000Z",
  "data": {
    "site_id": "SITE_ID",
    "lead_id": "LEAD_ID"
  }
}

Takrorsizlash kaliti sifatida tanadagi id yoki maf-event-iddan foydalaning. Yetkazish vaqti yoki yaratilgan database IDʼdan foydalanmang.

Node.jsʼda imzoni tekshirish#

JSON tahlilidan oldin aynan xom baytlarni o‘qing. Imzolangan qiymat TIMESTAMP + "." + RAW_BODY.

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

export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  const supplied = values.v1;
  if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;

  const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}

Noto‘g‘ri imzo va qabul qilingan replay oynasidan eski vaqtni rad eting; besh daqiqa odatiy boshlang‘ich qiymat. Bir xil uzunlikdagi baytlarni doimiy vaqtda taqqoslang.

Pythonʼda imzoni tekshirish#

import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = values.get("t", "")
    supplied = values.get("v1", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, supplied)

Faqat imzo tekshiruvi muvaffaqiyatli bo‘lgandan keyin JSONʼni tahlil va qayta ishlang.

Qabul qilish va qayta ishlash#

1. Imzo va vaqtni tekshiring.
2. Event IDʼni unique constraint bor jadvalga kiriting.
3. U allaqachon mavjud bo‘lsa, yon taʼsirni takrorlamasdan 204 qaytaring.
4. Hodisani commit qiling yoki ichki vazifani navbatga qo‘ying.
5. Tezda 2xx javobini qaytaring.

Make Agent Fast yuboruvchisi 10 soniyadan keyin timeout qiladi. U faqat 2xxni muvaffaqiyatli deb biladi va redirectni kuzatmaydi.

Qayta urinish tartibi#

Ishlamagan yetkazishlar sakkiztagacha urinish uchun navbatga qo‘yiladi. Kutish taxminan ikki soniyadan boshlanadi, tasodifiy og‘ish bilan ikki barobar ortadi va bir soat bilan cheklanadi; worker band bo‘lsa, haqiqiy yetkazish kechroq bo‘lishi mumkin. Qayta urinish dastlabki so‘rovdan uzoqroq yashashi va tartibsiz kelishi mumkinligi uchun bir hodisa boshqasidan darhol oldin kelishiga tayanmang.

Faqat Make Agent Fast qayta urinishi kerak bo‘lganda non-2xx qaytaring. Doimiy qo‘llab-quvvatlanmaydigan event versiyasi yoki o‘chirilgan manzil uchun cheksiz vaqtinchalik xato chiqarish o‘rniga uni qabul qilib qayd eting yoki endpointni olib tashlang.

Imzolash sirini yangilash#

Imzolash sirini qayta ko‘rsatish yoki tahrirlash mumkin emas. Xavfsiz yangilash uchun:

1. Vaqtinchalik yoki versiyalangan qabul qiluvchi yo‘liga qaragan ikkinchi endpoint yarating.
2. Uning yangi ko‘rsatilgan sirini saqlang.
3. Ikkala endpointdan hodisalarni qabul qiling va takrorsizlang.
4. Yangi endpoint haqiqiy yetkazish olayotganini tekshiring.
5. Eski endpointni DELETE /webhook-endpoints/{endpoint_id} bilan o‘chiring.

Qabul qiluvchi URL bir xil qolsa, kesishuv davrida ilova ikkala sirni ham qabul qilsin va takroriy yon taʼsirni event ID orqali to‘xtatsin.

Muammolarni hal qilish#

Yordam xabariga imzolash siri, bearer kaliti yoki to‘liq tashrifchi payloadini kiritmang. Endpoint ID, event ID, xato vaqti va shaxsiy maʼlumotsiz qabul qiluvchi loglarini qo‘shing.