Webhook call event

1. Set up Webhook

Partners need to provide Alohub with the following information:

Information	Description
Webhook URL	URL to receive the webhook (HTTPS recommended). For example: https://your-server.com/api/alohub/webhook
Method	POST
Authorization Key	Authentication key — Alohub will send it in the header Authorizationof each request
Content-Type	application/json

How to register: Contact the Alohub technical team, provide the webhook receiving URL and authentication key. Alohub will configure to send events to your URL. , cung cấp URL nhận webhook và key xác thực. Alohub sẽ cấu hình gửi sự kiện đến URL của bạn.

2. Sample Payload

Each time a call ends, Alohub sends a POST request with the following JSON body:

{
  "call_id": "20240113150030xxxxxx",
  "call_status": "answered",
  "direction": "outbound",
  "caller_number": "03899xxx",
  "destination_number": "888",
  "starttime": "2024-01-13 15:00:30",
  "answertime": "2024-01-13 15:00:35",
  "endtime": "2024-01-13 15:05:30",
  "hangup_by": "customer",
  "hotline": "",
  "total_duration": "300",
  "holding_duration": "0",
  "recording_url": "https://domain:port/IPCCMedia/MP3Export.do?url=file.mp3&source=ipcc",
  "objectId": 1,
  "transactionID": "TRANSID_1111",
  "userName": "adminxxx",
  "eventType": "call"
}

3. Details of data fields

Field	Type	Description
call_id	string	Unique identifier of the call
call_status	string	Call status (see status code table below)
direction	string	Call direction: inbound(incoming) / outbound(outgoing)
caller_number	string	Caller phone number (customer)
destination_number	string	Extension number of the agent who answered
starttime	string	Call start time ( YYYY-MM-DD HH:mm:ss)
answertime	string	Time the call was answered
endtime	string	Call end time
hangup_by	string	Party that hung up: customer(customer), agent(agent), system(system)
hotline	string	Hotline number (main number), empty if none
total_duration	string	Total call duration (seconds)
holding_duration	string	Hold time (seconds)
recording_url	string	URL of the call recording file (used for download or playback)
objectId	number	Related object ID (default: 1)
transactionID	string	Transaction ID (passed when calling makeCall or addCampaignCustomer)
userName	string	Agent account name handling the call
eventType	string	Event type, default "call"

4. Call status codes

Value call_statusin the webhook payload:

Status code	Description	Notes
answered	Call has been answered	Call successful, connection between both parties
noanswer	No answer	Ringing but the recipient did not pick up
busy	Line busy	Recipient is on another call or declined
failed	Call failed	Technical error: number does not exist, network error, out of resources
cancel	Call canceled	Agent or system canceled before connection

5. Handling Webhook on the partner side

Quick response: The endpoint receiving the webhook should return HTTP 200within 5 seconds . If timeout or error, Alohub will retry up to 3 times with increasing intervals.

Sample code for handling webhook

const express = require('express')
const app = express()
app.use(express.json())

app.post('/api/alohub/webhook', (req, res) => {
  const { call_id, call_status, caller_number, direction, recording_url } = req.body

  console.log(`Cuộc gọi ${call_id}: ${call_status}`)
  console.log(`Hướng: ${direction}, SĐT: ${caller_number}`)

  if (recording_url) {
    console.log(`Ghi âm: ${recording_url}`)
  }

  // Xử lý logic nghiệp vụ tại đây
  // VD: cập nhật CRM, gửi notification, lưu DB...

  // Quan trọng: respond 200 ngay lập tức
  res.status(200).json({ received: true })
})

app.listen(3000)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/alohub/webhook', methods=['POST'])
def webhook():
    data = request.json

    call_id = data.get('call_id')
    call_status = data.get('call_status')
    caller_number = data.get('caller_number')
    recording_url = data.get('recording_url')

    print(f"Cuộc gọi {call_id}: {call_status}, SĐT: {caller_number}")

    if recording_url:
        print(f"Ghi âm: {recording_url}")

    # Xử lý logic nghiệp vụ tại đây

    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(port=3000)

6. Important notes

Idempotency: You may receive the same event multiple times (due to retry). Use call_idas a key to check for duplicates before processing.

Security: Verify the header Authorizationin the webhook request matches the key you provided to Alohub. Reject invalid requests.

Best practice: Receive webhook → respond 200 immediately → push to queue (Redis, RabbitMQ...) → process async. Avoid heavy processing in the webhook handler.