Hubz API quick start

1. Create an integration key

1. Sign in to Hubz as the business owner: only the business owner can create keys.
2. Open Integrations, create a key, choose its scopes (read, send, link, events) and the Zalo accounts it may use.
3. Copy the hbz_live_… key and keep it like a password. The sample key in these docs is hbz_live_xxx.

2. Make your first request

GET /v1/me tells you which company the key belongs to, who it acts as and which Zalo accounts it can use:

curl https://api.hubz.vn/v1/me \
  -H "Authorization: Bearer hbz_live_xxx"

Then list the Zalo accounts the key can use, or find a customer by phone number (any way of writing the number works):

curl https://api.hubz.vn/v1/accounts \
  -H "Authorization: Bearer hbz_live_xxx"

curl "https://api.hubz.vn/v1/contacts?phone=0912345678" \
  -H "Authorization: Bearer hbz_live_xxx"

3. Receive your first webhook

The key needs the events scope. Register your https address and the events you want:

curl -X PUT https://api.hubz.vn/v1/webhook \
  -H "Authorization: Bearer hbz_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://crm.example.com/hubz/webhook", "events": ["message.created", "conversation.updated"]}'

Hubz returns the signing secret (secret) when the webhook is created, when its address changes or when you send rotateSecret. Keep it to verify signatures:

{
  "url": "https://crm.example.com/hubz/webhook",
  "events": ["message.created", "conversation.updated"],
  "secret": "…"
}

Send a test ping event; the result comes back at once:

curl -X POST https://api.hubz.vn/v1/webhook/test \
  -H "Authorization: Bearer hbz_live_xxx"

{"ok": true, "status": 200, "error": null}

Next

• Webhooks: events, retries and signature checks with samples.
• Missed events when your software cannot receive webhooks.
• API reference: every endpoint.