Ma'lumot webhooklari

Webhooklar mijoz ma'lumoti o'zgarganda Bito sizga xabar berishini ta'minlaydi, shunda API'ni doimiy so'rab turish shart emas. Manzil ikki yo'l bilan paydo bo'ladi:

• integratsiyadagi webhook_uri — Bito uni har bir o'rnatishda avtomatik obuna qiladi;
• webhook/subscribe — Integration API orqali, har bir manzil uchun alohida, o'zingiz tanlagan hodisalar bilan.

webhook_uri: avtomatik obuna

Integratsiyada webhook_uri ko'rsatilgan bo'lsa, integratsiya har safar o'rnatilganda Bito shu manzilni quyidagi kolleksiyalarning create, update va delete hodisalariga obuna qiladi: currencies, customers, trades, users, productCategories, products, unitsOfMeasure, saleOrders, invoices, transactions, purchases, purchaseReturns, purchaseOrders.

status_change bu yo'l bilan yuborilmaydi — kerak bo'lsa, webhook/subscribe orqali alohida obuna bo'ling. O'chirish bu obunani o'chiradi, qayta o'rnatish esa uni qaytadan yaratadi.

Hodisalar ro'yxati

POST /integration/api/v2/webhook/events obuna bo'lish mumkin bo'lgan hamma narsani qaytaradi. Hodisa nomlari — <kolleksiya>.<amal>.

Response (qisqartirilgan)

{
    "code": 0,
    "data": [
        {
            "collection_name": "saleOrders",
            "actions": ["create", "update", "delete", "status_change"],
            "events": [
                "saleOrders.create",
                "saleOrders.update",
                "saleOrders.delete",
                "saleOrders.status_change"
            ]
        },
        {
            "collection_name": "customers",
            "actions": ["create", "update", "delete"],
            "events": ["customers.create", "customers.update", "customers.delete"]
        }
    ],
    "time": "2025-01-15T10:30:00.000Z"
}

Amal	Qachon ishlaydi
create	Yozuv yaratilganda
update	Yozuv o'zgartirilganda
delete	Yozuv o'chirilganda
status_change	Yozuv statusi o'zgarganda. Faqat statusi bor kolleksiyalar uchun mavjud — qaysilari ekanini events murojaati ko'rsatadi.

Obuna bo'lish

POST /integration/api/v2/webhook/subscribe. Murojaat bitta destination doirasida upsert kabi ishlaydi: qayta yuborilsa, o'sha manzilning hodisalar ro'yxatini almashtiradi va qolgan manzillaringizga tegmaydi.

Request

POST /integration/api/v2/webhook/subscribe
api-key: mycompany:9ad41c0e7b3f28d5610ac94e7f1b26d8
Content-Type: application/json

{
    "destination": "https://your-app.example.com/bito/webhook",
    "events": ["saleOrders.create", "saleOrders.status_change", "customers.update"]
}

Response

{
    "code": 0,
    "data": {
        "destination": "https://your-app.example.com/bito/webhook",
        "events": ["saleOrders.create", "saleOrders.status_change", "customers.update"],
        "secret": "d7c1904ae5b3268f04ad91c7e63b58f2019ce74db28a1650f3c9e7a84b2d6015"
    },
    "time": "2025-01-15T10:30:00.000Z"
}

Endpoint	Tanasi	Kim chaqira oladi
POST webhook/events	-	Integratsiyaning istalgan avtorizatsiyalangan foydalanuvchisi
POST webhook/get-all	-	Integratsiyaning istalgan avtorizatsiyalangan foydalanuvchisi
POST webhook/subscribe	{ destination, events[] }	Akkaunt egasi yoki qo'shimcha egasi
POST webhook/unsubscribe	{ destination }	Akkaunt egasi yoki qo'shimcha egasi

subscribe va unsubscribe so'rov kimning nomidan bajarilayotganini tekshiradi: user_id sarlavhasi bilan oddiy xodim nomidan yuborilgan murojaat rad etiladi.

Cheklovlar: bitta integratsiyaga ko'pi bilan 100 ta turli manzil, bitta subscribe murojaatida ko'pi bilan 500 ta hodisa; subscribe va unsubscribe — soniyasiga 1 ta so'rov.

Yetkazilgan xabarni qabul qilish

Bito nima yuboradi

POST https://your-app.example.com/bito/webhook
account-id: 507f1f77bcf86cd799439011
X-Bito-Signature: t=1736937000,v1=6b1f0a...c94e
Content-Type: application/json

{"collection_name":"saleOrders","action":"status_change","id":"6712f0a9c4d1e87b3a0f9911","organization_id":"6712f0a9c4d1e87b3a0f7788"}

Tanada o'zgargan yozuvning identifikatori keladi, o'zgarishning o'zi emas. id bo'yicha joriy yozuvni odatdagi v2 o'qish endpointlaridan, account-id sarlavhasidagi akkaunt doirasida oling.

Sarlavha	Qachon bor	Ma'nosi
account-id	Doim	Hodisa sodir bo'lgan akkaunt
X-Bito-Signature	Doim	Imzo — pastda
api-key	Faqat webhook_uri obunasida	Bito shu obuna uchun yaratgan token. Bu sizning integratsiya api_keyingiz emas — undan API'ga murojaat qilish uchun foydalanmang. webhook/subscribe orqali yaratilgan obunalar api-key sarlavhasini yubormaydi.

Bito javobni 10 soniya kutadi va qayta yo'naltirishlarga (3xx) ergashmaydi. 10 soniyada kelmagan yoki 2xx bo'lmagan javob muvaffaqiyatsiz yetkazish hisoblanadi. Og'ir ishni navbatga qo'yib, darhol 2xx qaytaring.

Imzoni tekshirish

X-Bito-Signature ko'rinishi: t=<unix soniya>,v1=<hex>, bunda v1 — HMAC_SHA256(secret, "{t}.{raw_body}"). secret — bu mijoz siringiz (client_secret); subscribe va get-all ham aynan shu qiymatni qaytaradi. U barcha akkauntlar va barcha manzillar uchun bitta, qayta o'rnatishda o'zgarmaydi va faqat sirni yangilaganingizda almashadi.

Tekshirish namunasi

import { createHmac, timingSafeEqual } from 'crypto';

// `raw` MUST be the untouched request body bytes. Do NOT JSON.parse and
// re-stringify before verifying -- key order and number formatting will differ
// and the signature will never match.
export function verify(raw: string, header: string, secret: string): boolean {
    const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
    const t = parts.t;
    const v1 = parts.v1;
    if (!t || !v1) return false;

    // Reject anything older than 5 minutes to blunt replay.
    if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false;

    const expected = createHmac('sha256', secret).update(`${t}.${raw}`).digest('hex');
    const a = Buffer.from(expected, 'hex');
    const b = Buffer.from(v1, 'hex');
    return a.length === b.length && timingSafeEqual(a, b);
}

WARNING

So'rov tanasining xom baytlarini hesh qiling. Bu Bito webhooklari bilan ishlashda eng ko'p uchraydigan xato. Agar siz HMAC hisoblashdan oldin tanani JSON.parse qilib, qaytadan seriyalashtirsangiz, kalitlar tartibi, bo'shliqlar yoki sonlar formati farq qilgan zahoti siz hesh qilgan baytlar Bito hesh qilgan baytlardan farq qiladi — va imzo hech qachon mos kelmaydi. Avval tegilmagan tana bo'yicha imzoni tekshiring, keyingina JSON'ni ajrating.

Webhooklar nimani kafolatlamaydi

WARNING

• Bitta urinish, takror yo'q. Qayta yuborish ham, kechiktirish ham, yetkazilmaganlar navbati ham yo'q. Manzilingiz ishlamayotgan bo'lsa, o'sha hodisa yo'qoladi.
• Tartib kafolatlanmaydi. Xabarlar tartibsiz kelishi mumkin.
• Ommaviy amallar umuman hodisa yaratmaydi. Ommaviy import va guruhli o'zgartirishlar webhook yubormaydi. Webhookni ma'lumotni qayta o'qishga sabab deb biling, ma'lumotning o'zi deb emas, va vaqti-vaqti bilan to'liq o'qish orqali solishtirib turing. Webhooklar to'liq deb hisoblagan integratsiya sezdirmay haqiqatdan uzoqlashib ketadi.