Hipcall Developers Knowledgebase / Use Cases

Transfer Call Details and Voice Recordings to Your Own System Using Webhooks.

Learn how to automatically download the audio file and add the detail record to your database as soon as the call ends.

Updated October 22, 2026
Read 5 min
On this page

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

  1. In your Hipcall dashboard, go to Settings > Developer > Webhooks.
  2. Click Add New Webhook.
  3. 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
  1. 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 5007 and 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.

Was this article helpful?