Overview
Hipcall provides call detail records (CDRs) via the dashboard and REST API. However, many teams need to transfer this data directly to their own systems, such as a data warehouse, compliance archive, CRM, or custom analytics dashboard. The call.ended webhook is designed specifically for streaming this data the moment a conversation concludes.
This guide explains how to receive the call.ended event, store the call details in your local database, and automatically download the audio recording before the presigned URL expires.
How it works
When a call ends, Hipcall sends a call.ended webhook to your endpoint. Your server parses the payload, inserts the call record into your database, and, when a recording URL is present, downloads the audio file in the background.
Architecture
flowchart TD
A["Call ends"] --> B["Hipcall sends call.ended webhook"]
B --> C["Your server receives payload"]
C --> D["Save CDR to database"]
D --> E{"record_url exists?"}
E -- "Yes" --> F["Download audio file in background"]
E -- "No" --> G["Complete"]
F --> H["Save MP3 locally and update record path"]
Step 1: Create the webhook in Hipcall
- In your Hipcall dashboard, go to Settings > Developer > Webhooks.
- Click Add New Webhook.
- Configure the webhook with these settings:
| Field | Value |
|---|---|
| Target URL | https://your-server.example.com/webhook/hipcall-cdr |
| Events | call.ended (Call Ended) |
| Method | POST |
- Enable Recording Links. When active, the webhook payload includes the temporary
record_url.
Local development: Use ngrok to expose your local workstation. Run
ngrok http 5007and configure the generated HTTPS URL as your target.
Step 2: Receive the webhook
When a call finishes, Hipcall delivers a JSON payload with the following structure:
{
"id": "msg_01j8m4k8c9p2x4r7v3z1a9b2c3",
"type": "call.ended",
"timestamp": "2026-10-01T10:00:45Z",
"data": {
"uuid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e6f8a0b43",
"direction": "inbound",
"caller_number": "+447700XXXXXX",
"callee_number": "+442079XXXXXX",
"started_at": "2026-10-01T10:00:00Z",
"answered_at": "2026-10-01T10:00:06Z",
"bridged_at": "2026-10-01T10:00:06Z",
"ended_at": "2026-10-01T10:00:45Z",
"call_duration": 39,
"missing_call": false,
"missing_call_reason": null,
"hangup_by": "contact",
"record_url": "https://storage.hipcall.com/recordings/call_123.mp3?X-Amz-Expires=604800&...",
"voicemail_id": null,
"voicemail_url": null,
"user_id": 1001,
"contact_id": 2002,
"channel_id": 3003,
"number_id": 3003,
"company_id": 4004
}
}
Key fields:
| Field | Description |
|---|---|
uuid |
Unique call identifier: use this as a primary key to prevent duplication. |
caller_number / callee_number |
Call participants in E.164 format. |
direction |
"inbound" or "outbound". |
call_duration |
Talk duration in seconds. |
record_url |
Presigned AWS S3 link to the MP3 file: valid for 7 days. |
hangup_by |
Party terminating the call: "contact", "user", or "system". |
Return an HTTP 200 response promptly; defer heavy operations to a background task.
Step 3: Store the CDR
Check for the call.ended event in the request. Use the uuid as the primary key to handle any webhook retries idempotently.
from flask import Flask, request, jsonify
import sqlite3
app = Flask(__name__)
@app.route('/webhook/hipcall-cdr', methods=['POST'])
def receive_cdr():
payload = request.json or {}
event_name = payload.get('type') or payload.get('event')
if event_name not in ('call.ended', 'call_hangup'):
return jsonify({"status": "ignored"}), 200
data = payload.get('data', {})
uuid = data.get('uuid')
if not uuid:
return jsonify({"status": "no_uuid"}), 200
# Deduplication check: Hipcall may retry upon timeout
conn = sqlite3.connect('calls.db')
cursor = conn.cursor()
cursor.execute('SELECT 1 FROM cdrs WHERE uuid = ?', (uuid,))
if cursor.fetchone():
conn.close()
return jsonify({"status": "exists"}), 200
cursor.execute('''
INSERT INTO cdrs
(uuid, caller_number, callee_number, direction,
duration, started_at, ended_at, record_url, hangup_by)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
''', (
uuid,
data.get('caller_number'), data.get('callee_number'),
data.get('direction'), data.get('call_duration'),
data.get('started_at'), data.get('ended_at'),
data.get('record_url'), data.get('hangup_by'),
))
conn.commit()
conn.close()
return jsonify({"status": "success"}), 201
Step 4: Download the audio recording
The record_url is a presigned URL that expires after a defined window. Download the file in a background thread so your webhook endpoint acknowledges the event immediately.
Pause for a few seconds before requesting the file: the audio upload to cloud storage completes right after hangup, and a brief delay guarantees file readiness.
import time
import requests
import threading
def download_recording(record_url, uuid):
time.sleep(3) # Wait for storage availability
try:
response = requests.get(record_url, stream=True, timeout=30)
if response.status_code == 200:
path = f"./data/records/{uuid}.mp3"
with open(path, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
conn = sqlite3.connect('calls.db')
cursor = conn.cursor()
cursor.execute(
'UPDATE cdrs SET local_record_path = ? WHERE uuid = ?',
(f"/api/records/{uuid}.mp3", uuid)
)
conn.commit()
conn.close()
except Exception as ex:
print(f"Download error ({uuid}): {ex}")
# Trigger background download after saving the CDR
record_url = data.get('record_url')
if record_url:
threading.Thread(
target=download_recording,
args=(record_url, uuid),
daemon=True
).start()
Tools used
| Tool | Purpose |
|---|---|
| Webhooks | Receives the call.ended event upon call termination. |
| Flask & SQLite | Lightweight HTTP listener and CDR storage. |
| Requests & Threading | Asynchronous audio file downloads without request latency. |
Next steps
- Validate webhook signatures to verify request authenticity.
- Archive recordings directly to Amazon S3 or Google Cloud Storage.
- Run a nightly reconciliation job to backfill any missed calls.