Overview
When an agent answers a call, every second counts. Instead of searching through a CRM to find out who is calling, the agent should see the caller's name, company, and account balance automatically, before they even say hello.
This guide shows how to combine Webhooks and the Insight Card API to display real-time caller data on the agent screen the moment a call connects.
How it works
The integration uses two Hipcall developer tools:
- Webhooks: Hipcall sends a
call.initiatedevent to your server when a call starts. - Insight Card API: Your server looks up the caller and pushes a card to Hipcall, which displays it on the agent's screen.
Architecture
flowchart TD
A["Incoming call"] --> B["Hipcall sends call.initiated webhook"]
B --> C["Your server receives event"]
C --> D{"Match found in CRM/ERP?"}
D -- "Yes" --> E["POST to Insight Card API"]
D -- "No" --> F["Skip"]
E --> G["Agent sees caller info on screen"]
Step 1: Receive the webhook
Subscribe to the call.initiated event in Settings > Developer > Webhooks. Hipcall will POST a JSON payload to your endpoint when every call starts (both inbound and outbound).
Example webhook payload:
{
"id": "msg_01j8m4k8c9p2x4r7v3z1a9b2c3",
"type": "call.initiated",
"timestamp": "2026-09-29T14:13:23Z",
"data": {
"credited": null,
"team_touch_at": null,
"first_touch_duration": null,
"contact_id": null,
"callee_id": null,
"answered_at": null,
"voicemail_url": null,
"caller_number": "+442045205757",
"missing_call_reason": null,
"call_duration": null,
"callback_time": null,
"call_flow": [
{
"action": "init",
"detail": {
"id": null,
"type": "contact"
},
"timestamp": 1790691203
}
],
"direction": "outbound",
"callee_number": "+447700900123",
"voicemail_id": null,
"callback_user_id": null,
"callee_type": "contact",
"ended_at": null,
"missing_call": null,
"channel_type": "number",
"callback_cdr_uuid": null,
"voicemail_type": null,
"caller_id": null,
"started_at": "2026-09-29T14:13:23Z",
"bridged_at": null,
"channel_id": 942,
"caller_type": null,
"user_id": 4200,
"hangup_by": null,
"uuid": "410c92c5-2b61-4dd2-aa75-xxxxxxxxxxxx",
"record_url": null,
"number_id": 942,
"company_id": 80719
}
}
Extract data.uuid (the call ID) and the customer's phone number:
- Inbound call: customer is
data.caller_number - Outbound call: customer is
data.callee_number
Step 2: Look up caller data in your CRM or ERP
Use the customer's phone number to query your data source (a database, CRM API, or ERP system).
Example response from your CRM:
{
"full_name": "Jane Smith",
"company": "Acme Corp",
"balance": "4250.00"
}
If no match is found, skip the Insight Card call entirely and return an immediate 200 OK response to the webhook.
Step 3: Push the card to the Insight Card API
Call the Insight Card API with the call_id from the webhook to associate the card with the active call.
Endpoint:
POST https://use.hipcall.com/api/v3/calls/{call_id}/cards
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Request body:
{
"card": [
{
"type": "title",
"text": "Hipcall Insight",
"link": "https://www.hipcall.com"
},
{
"type": "shortText",
"label": "Name",
"text": "Jane Smith"
},
{
"type": "shortText",
"label": "Company",
"text": "Acme Corp"
},
{
"type": "shortText",
"label": "Balance",
"text": "£4,250.00"
}
]
}
The card appears on the agent's Webphone within milliseconds of the call starting.
Supported row types:
| Row Type | Fields | Description |
|---|---|---|
title |
type, text, link |
Main card header. Clickable when link is provided. |
shortText |
type, text, label, link, ios, android |
Two-column data row with label on the left and value on the right. |
user |
type, label, user_id |
Displays the name of a specific agent from their Hipcall user ID. |
Important considerations
- Each row type accepts only its predefined fields. For instance, sending
user_idin ashortTextrow results in a422 Unprocessable Entityresponse. Do not include null or irrelevant properties in row objects. - Do not send cards after a call ends. The API may accept the card, but the agent will not be able to view it.
- Acknowledge webhooks promptly. Return
200 OKin under 50 milliseconds and push the card asynchronously.
Tools used
| Tool | Purpose |
|---|---|
| Webhooks | Receive call.initiated event when a call starts |
| Insight Card API | Push caller data card to the agent's screen |
Next steps
- Match the caller's phone number with your CRM records and automatically route calls to different extensions based on customer status.
- Webhooks documentation: Subscribe to events, configure retry logic, verify signatures.
- REST API authentication: Set up API keys or OAuth 2.0 for your server.