Webhooks

Webhooks: оқиғалар туралы хабарламалар

Webhooks оқиғалар орын алғанда Сіздің серверіңізге HTTP-хабарламалар алуға мүмкіндік береді: кіріс хабарламалар, шығыс хабарламалар, мәртебелердің өзгеруі және басқалары.

Қалай жұмыс істейді

1. Сіз серверіңіздің URL мекенжайын PATCH /v1/webhooks арқылы тіркейсіз
2. WazzaBee Сіздің URL-ге тексеру сұрауын жібереді: ол 200 қайтармаса, тіркеу қабылданбайды
3. Оқиғалар орын алғанда WazzaBee Сіздің URL-ге оқиға деректерімен POST-сұрау жібереді
4. Әр сұрауға HMAC-SHA256 қолтаңбасы қойылады, сондықтан оның түпнұсқалығын тексере аласыз

Webhook қосудың екі тәсілі

1. Жеке кабинет арқылы (оңай, бағдарламашысыз). «Коннекторлар» → «API» → «Кіріс хабарламаларға арналған webhook» блогын ашыңыз. Серверіңіздің мекенжайын қойып, «Қосу» батырмасын басыңыз: кабинет мекенжайды өзі тексеріп, қолтаңбаға арналған құпия кілтті көрсетеді.

2. REST API арқылы (автоматтандыру үшін). Төменде сипатталғандай PATCH /v1/webhooks сұрауын жіберіңіз.

Вебхук бір рет бапталады, сондықтан сұрауды өз серверіңізден жіберген ыңғайлы. Егер оны браузерден жіберіп, Failed to fetch қатесін көрсеңіз, әдістің бас әріптермен жазылғанын (PATCH) және мекенжайыңыз тексеру сұрауына 10 секундтан аспай 200 қайтаратынын тексеріңіз.

PATCH /v1/webhooks: тіркеу/жаңарту

URL

PATCH https://api.wazzabee.com/api-gateway/v1/webhooks

Тақырыптар

Authorization: Bearer ВАШ_API_КЛЮЧ

Content-Type: application/json

Сұрау денесінің параметрлері

Қолжетімді жазылымдар (subscriptions)

Сұрау мысалы

curl -X PATCH "https://api.wazzabee.com/api-gateway/v1/webhooks" \

  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \

  -H "Content-Type: application/json" \

  -d '{

    "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

    "subscriptions": [

      "messages_incoming",

      "messages_outgoing",

      "messages_status"

    ]

  }'

Сәтті жауап (200 OK)

{

  "success": true,

  "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

  "subscriptions": [

    "messages_incoming",

    "messages_outgoing",

    "messages_status"

  ],

  "secret": "a1b2c3d4e5f6...64-символьный-hex-ключ",

  "message": "Вебхук установлен. Сохраните secret, он используется для подписи уведомлений (HMAC-SHA256)."

}

Тексеру сұрауы

Вебхукті тіркеген кезде WazzaBee Сіздің URL-ге бірден тексеру POST-сұрауын жібереді:

{

  "test": true,

  "event": "webhook_test",

  "challenge": "случайная_строка_для_подтверждения",

  "timestamp": "2026-03-12T10:00:00.000Z",

  "message": "WazzaBee webhook test: если вы видите это, ваш webhook работает корректно."

}

Сіздің серверіңіз 200 мәртебесімен жауап беруі керек. Жауап 200 болмаса немесе URL қолжетімсіз болса, вебхукті тіркеу қатемен қабылданбайды.

Тіркеу кезіндегі ықтимал қателер

GET /v1/webhooks: ағымдағы баптаулар

URL

GET https://api.wazzabee.com/api-gateway/v1/webhooks

Сұрау мысалы

curl -X GET "https://api.wazzabee.com/api-gateway/v1/webhooks" \

  -H "Authorization: Bearer ВАШ_API_КЛЮЧ"

Жауап: вебхук бапталған (200 OK)

{

  "success": true,

  "webhook": {

    "webhooksUri": "https://ваш-сервер.com/webhook/wazzabee",

    "subscriptions": ["messages_incoming", "messages_outgoing"],

    "status": "active",

    "failureCount": 0,

    "createdAt": "2026-03-12T08:00:00.000Z",

    "updatedAt": "2026-03-12T08:00:00.000Z"

  }

}

Жауап: вебхук бапталмаған (200 OK)

{

  "success": true,

  "webhook": null,

  "message": "Вебхук не настроен"

}

Өрістердің сипаттамасы

Қайта жіберу

Егер Сіздің серверіңіз 10 секунд ішінде 2xx кодымен жауап бермесе (қате қайтарса, қолжетімсіз болса немесе үлгермесе), WazzaBee сол хабарламаны қайта жібереді. Әрекеттер арасындағы үзілістер ұлғая береді: 1 минут, 5 минут, 15 минут, 1 сағат, 3 сағат, 6 сағат, 12 сағат. Барлығы шамамен бір тәулікте 8 әрекет.

Әр жіберудің тақырыптары

Қайталау кейінгі хабарламалардан кешірек келуі мүмкін. Хабарламалардың ретін timestamp өрісі бойынша қалпына келтіріңіз.

Вебхук қашан ажыратылады

8 әрекеттің бірде-бірі сәтті болмаса, хабарлама жеткізілмеген болып саналады. Қатарынан 10 хабарлама жеткізілмегеннен кейін вебхук disabled мәртебесіне ауысады. Кез келген сәтті жеткізу есептегішті нөлге түсіреді. Барлық әрекеттер кабинеттегі жеткізу журналында көрінеді: «Коннекторлар» → «API».

Жеткізу мәртебелері (messages_status)

Ресми WhatsApp (WABA) желісінен жіберілген әр шығыс хабарлама бойынша мәртебенің өзгергені туралы хабарлама келеді. queueId мәні POST /v1/messages/send жауабындағы queueId мәнімен сәйкес келеді, мәртебені өз жіберуіңізбен сол арқылы салыстырыңыз. Жіберу кезінде campaignId берілген болса, ол да келеді.

{
  "statuses": [{
    "messageId": "uuid",
    "queueId": "uuid",
    "campaignId": "promo_oct",
    "channelId": "uuid",
    "chatId": "77071234567",
    "conversationId": "uuid",
    "contactId": "uuid",
    "status": "delivered",
    "error": null,
    "timestamp": "2026-09-30T12:00:00.000Z"
  }]
}

Дәл осы деректерді GET /v1/messages арқылы сұратуға болады: status, sentAt, deliveredAt, readAt, error өрістері.

Батырмаларды басу (messages_button)

Абонент шаблон батырмасын басқанда, кәдімгі кіріс хабарламадан бөлек жеке оқиға келеді. replyTo ішінде қай шығыс хабарламаға жауап берілгені көрсетілген: queueId, campaignId (API арқылы жіберудегі Сіздің белгіңіз) және broadcastId (шаблон кабинеттен таратылым ретінде жіберілсе). Бастапқы хабарламаны context бойынша өзіңіз іздеудің қажеті жоқ.

{
  "buttons": [{
    "messageId": "uuid",
    "channelId": "uuid",
    "chatId": "77071234567",
    "contactId": "uuid",
    "conversationId": "uuid",
    "button": { "type": "button", "id": null, "title": "Да, интересно", "payload": "YES_INTERESTED" },
    "replyTo": {
      "messageId": "uuid",
      "queueId": "uuid",
      "campaignId": "promo_oct",
      "broadcastId": null
    },
    "timestamp": "2026-09-30T12:00:00.000Z"
  }]
}

Бастапқы хабарлама табылмаса (мысалы, WazzaBee арқылы жіберілмесе), replyTo мәні null болады.

Өз тақырыптарыңыз бен мекенжайдағы параметрлер

Егер серверіңіз хабарламаларды тек авторизациямен қабылдаса, вебхукті тіркеу кезінде тақырыптарды headers өрісінде беріңіз. Олар әр хабарламамен, қайталаулармен және тексеру сұрауымен бірге жіберіледі. Статикалық деректерді (мысалы, жүйеңіздің идентификаторын) мекенжайға тікелей қосуға болады: https://ваш-сервер.com/hook?source=wazzabee&system=crm. Тақырыптарды кабинетте де беруге болады: «Коннекторлар» → «API» → вебхук блогы.

{
  "webhooksUri": "https://ваш-сервер.com/hook?source=wazzabee",
  "subscriptions": ["messages_incoming", "messages_status", "messages_button"],
  "headers": { "Authorization": "Bearer ваш-токен" }
}

Қолтаңбаны тексеру (HMAC-SHA256)

Әр хабарламаға вебхукті тіркеу кезінде алынған secret арқылы қолтаңба қойылады. Жалған сұраулардан қорғану үшін қолтаңбаны үнемі тексеруді ұсынамыз.

Node.js-те тексеру мысалы

const crypto = require("crypto");



function verifyWebhookSignature(body, signature, secret) {

  const expected = crypto

    .createHmac("sha256", secret)

    .update(JSON.stringify(body))

    .digest("hex");

  return signature === expected;

}



// В обработчике webhook:

app.post("/webhook/wazzabee", (req, res) => {

  const signature = req.headers["x-webhook-signature"];

  if (!verifyWebhookSignature(req.body, signature, YOUR_WEBHOOK_SECRET)) {

    return res.status(401).send("Invalid signature");

  }

  // Обработка события...

  res.status(200).send("OK");

});

Python-да тексеру мысалы

import hmac

import hashlib

import json



def verify_signature(body: dict, signature: str, secret: str) -> bool:

    expected = hmac.new(

        secret.encode(),

        json.dumps(body).encode(),

        hashlib.sha256

    ).hexdigest()

    return hmac.compare_digest(signature, expected)



# В обработчике Flask:

@app.route("/webhook/wazzabee", methods=["POST"])

def handle_webhook():

    signature = request.headers.get("X-Webhook-Signature", "")

    if not verify_signature(request.json, signature, YOUR_WEBHOOK_SECRET):

        return "Invalid signature", 401

    # Обработка события...

    return "OK", 200

Кіріс webhook-хабарламаның пішімі

Кіріс хабарлама түскенде WazzaBee Сіздің URL-ге мына құрылымдағы POST-сұрау жібереді:

{
  "channel_id": "uuid",
  "channel_type": "whatsapp_waba",
  "channel_name": "WhatsApp Business",
  "conversation_id": "uuid",
  "message": {
    "id": "msg_id",
    "from": "77771234567",
    "sender_name": "Клиент",
    "type": "text",
    "text": "Здравствуйте!",
    "timestamp": "1712345678"
  },
  "operator": {
    "crm_user_id": "manager-42",
    "crm_user_name": "Алексей Менеджер"
  },
  "ad": {
    "ad_id": "120255518599590051",
    "source_type": "ad",
    "headline": "Visa4U",
    "text": "Отказали в визе? Не все потеряно!",
    "media_type": "video",
    "image_url": "https://scontent.xx.fbcdn.net/...jpg",
    "video_url": "https://video.xx.fbcdn.net/...mp4",
    "url": "https://fb.me/2abcXYZ",
    "click_id": "AfgHqhgPqgcChoXjlCqLkHfWKeS8"
  },
  "raw": { ... }
}

Өрістердің сипаттамасы

ad блогы: өтініштің көзі

Егер клиент Instagram немесе Facebook жарнамасында «WhatsApp-қа жазу» батырмасын басса, хабарламамен бірге ad блогы келеді. Кәдімгі өтініштерде ол болмайды: ішіндегі мәндерді емес, өрістің өзі бар-жоғын тексеріңіз. Блок тек ресми WhatsApp желілерінде келеді: мұндай деректерді Meta тек WABA бойынша береді.

Клиенттердің WABA-шаблон батырмаларына жауаптары

Сіз клиентке Quick Reply (немесе Interactive buttons / list) батырмалары бар мақұлданған WABA-шаблонын жіберіп, клиент батырманы басқанда, WazzaBee webhook-ке қосымша message.interactive және message.context өрістерін жібереді. message.text өрісінде басылған батырманың нақты мәтіні болады, оны CRM чатында клиенттің кәдімгі хабарламасы ретінде көрсетуге болады.

message.type мәндері

message.interactive өрісінің құрылымы

{

  "type": "button" | "button_reply" | "list_reply",

  "id":    "идентификатор кнопки" | null,

  "title": "текст кнопки, который видел клиент" | null,

  "description": "описание (только для list_reply)" | null,

  "payload": "значение payload (только для type=button)" | null

}

message.context өрісінің құрылымы

Клиент батырмасын басқан бастапқы HSM-хабарламаға сілтеме:

{

  "id":          "uuid исходящего сообщения в WazzaBee",

  "from":        "номер отправителя (ваш WABA-номер)",

  "gs_id":       "внутренний ID сообщения у провайдера",

  "meta_msg_id": "wamid.HBgL... (ID в Meta)"

}

Webhook мысалы: клиент «Да, буду вовремя» батырмасын басты

{

  "channel_id": "f0e8...",

  "channel_type": "whatsapp_waba",

  "channel_name": "WhatsApp Business",

  "conversation_id": "b1c2...",

  "message": {

    "id": "wamid.HBgLNzcwMTEwMDEwNTkVAgASGBQzQTY5NkJCNjE3M0JGQjE1MjVEMQA=",

    "from": "77011001059",

    "sender_name": "Фархат",

    "type": "button",

    "text": "Да, буду вовремя",

    "interactive": {

      "type": "button",

      "title": "Да, буду вовремя",

      "payload": "Да, буду вовремя"

    },

    "context": {

      "id": "584abab5-911a-49ca-a750-95e8116be1e1",

      "from": "77079119977",

      "gs_id": "378ba4ed-5a5d-4c58-a4e8-b6ca08b2ad7a",

      "meta_msg_id": "wamid.HBgL..."

    },

    "timestamp": "1776870877"

  },

  "operator": null,

  "raw": { ... }

}

Мысал: Interactive list басу (Meta Cloud API v3)

{

  "message": {

    "type": "interactive",

    "text": "Доставка на дом",

    "interactive": {

      "type": "list_reply",

      "id": "delivery_home",

      "title": "Доставка на дом",

      "description": "По адресу клиента"

    },

    "context": { "meta_msg_id": "wamid.HBgL..." }

  }

}

Шығыс WABA-шаблондары (messages_outgoing)

Сіз HSM-шаблонын API арқылы немесе WazzaBee интерфейсінен жібергенде, messages_outgoing жазылымы болса, webhook-ке template өрісі бар құрылым келеді (шаблонда батырмалар болса):

{

  "messages": [{

    "messageId": "uuid",

    "direction": "outgoing",

    "type": "template",

    "text": "Здравствуйте! Подтвердите встречу завтра в 15:00.",

    "template": {

      "name": "appointment_reminder_v2",

      "language": "ru",

      "buttons": [

        { "type": "quick_reply", "text": "Да, буду вовремя" },

        { "type": "quick_reply", "text": "Перенести" }

      ]

    },

    "timestamp": "2026-04-22T15:14:42Z"

  }]

}

Бұл Сіздің CRM-ға чат лентасында батырмаларды клиенттің WhatsApp-та көргеніндей етіп дәл салуға мүмкіндік береді.

Шығыс хабарламаны кім жіберді (author)

messages_outgoing оқиғасы клиентке берілген кез келген жауапқа келеді: WazzaBee кабинетінде оператор жазған, Сіздің CRM-ға кірістірілген чаттан жіберілген, шаблонмен немесе POST /v1/messages/send арқылы жіберілген. Хабарламамен бірге author блогы келеді: нақты кім жауап бергені.

{
  "messages": [{
    "messageId": "uuid",
    "channelId": "uuid",
    "chatId": "77001234567",
    "contactId": "uuid",
    "conversationId": "uuid",
    "direction": "outgoing",
    "type": "text",
    "text": "Здравствуйте! Ваши документы готовы.",
    "author": {
      "kind": "operator",
      "name": "Назерке А.",
      "userId": "manager-42"
    },
    "timestamp": "2026-07-30T09:20:12.000Z"
  }]
}

author блогының өрістері