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

Аталыштар (headers)

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":          "WazzaBee'деги чыгуучу билдирүүнүн uuid'и",
  "from":        "жөнөтүүчүнүн номери (сиздин WABA-номериңиз)",
  "gs_id":       "провайдердеги билдирүүнүн ички ID'си",
  "meta_msg_id": "wamid.HBgL... (Meta'дагы ID)"
}

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 блогунун талаалары