Hipcall Developers Knowledgebase / Webhooks

How to Build a Hipcall Webhook Receiver in .NET

Build an ASP.NET Core webhook receiver for Hipcall, store calls idempotently, and keep your archive complete when delivery fails.

Updated October 22, 2026
Read 22 min
On this page

Overview

Polling the API for call records uses up requests and delivers data late. A webhook works the other way around: Hipcall sends an HTTP POST to your server when something happens, so a finished call reaches your database within a few seconds.

Webhook v2 changes what a receiver has to do. Every request is signed, and a failed delivery is retried up to 10 times over about 3 days. You must verify the signature, and you must expect the same event more than once. The format follows the open Standard Webhooks specification, so signature libraries for many languages work with it.

This article builds a receiver with ASP.NET Core Minimal API. It does four things:

  • Verifies the signature before it parses the body.
  • Skips deliveries it has already handled.
  • Keeps one record per call, even when events arrive out of order.
  • Downloads the recording without delaying the response.

The headers, payloads, and timings below come from two outbound test calls in a Hipcall demo account. Phone numbers are masked.

Before you start

You need:

  • .NET 8 SDK. dotnet --version must print 8.0 or higher.
  • A Hipcall plan that includes API access. Webhooks come with those plans.
  • Permission to manage developer settings, so you can open Settings > Developer > Webhooks.
  • Permission to see communication content, if you want recording links. The API applies the same rule.
  • A way to place test calls from the account.
  • A public HTTPS address. Hipcall does not send to plain HTTP and does not follow redirects. For local work, expose port 5080 with a tunnel such as ngrok:
ngrok http 5080

Each account can have up to 3 webhooks by default.

Set up the webhook

  1. Open Settings > Developer > Webhooks and add a new webhook.
  2. In the Endpoint card, enter a Name (it appears in the webhook list and in emails) and a URL, for example https://your-server.example.com/hipcall/events. The Description is optional.
  3. In the Events card, tick call.initiated, call.connected, and call.ended. The panel warns that events carry personal data such as names and phone numbers, so send them only to an address you control.
  4. In the Recording links card, choose whether to send listening links. The setting is off by default. When it is on, call events carry record_url and voicemail_url links that stay valid for 7 days, and anyone who has a link can listen. When it is off, those two fields are empty, but has_recording is still sent. Hipcall records who turned the setting on. If that person later loses permission to see communication content, the links arrive empty. The test calls in this article were made with the setting on.
  5. Select Create.

The webhook page has five tabs: General, Events, Signing secret, Deliveries, and Code examples.

Open Signing secret. The secret starts with whsec_ and is hidden at first. Select Show to reveal it. Hipcall writes that action to the audit log. Keep the secret in an environment variable, never in your code:

export HIPCALL_WEBHOOK_SECRET="whsec_..."

On Windows PowerShell:

$env:HIPCALL_WEBHOOK_SECRET = "whsec_..."

Rotate creates a new secret. The new one works immediately, and the old one stays valid for 24 more hours. During that time every request carries two signatures, so you can deploy the new secret without losing events. If the old secret leaked, do not wait for the 24 hours. Revoke it right away.

The Code examples tab shows how to verify the signature in several languages, such as Node.js, Python, and PHP. C# is not among them, so the example below writes the check by hand.

Back on the General tab, Send test event sends a signed webhook.test event to your URL. Use it to check your setup before real calls arrive, then look at the Deliveries tab for the result.

Receive your first event

Create a new web project:

dotnet new web -n Hipcall.WebhookReceiver

Then add the receiver code to Program.cs.

Start the receiver, then place a call. Hipcall sends one request per event, so a normal call produces three requests: call.initiated, call.connected, and call.ended.

Each request has these headers:

POST /hipcall/events HTTP/1.1
content-type: application/json
user-agent: Hipcall-Webhooks/1.0
webhook-id: evt_2nb7kq4xyc8vfr1tlm0pzab3cd
webhook-timestamp: 1792657626
webhook-signature: v1,g3qmK3e9Fz7xY2qL9vBn1sD4cE6wZ8uI0oP1rT3vX5y=
  • webhook-id identifies the event. It is the same on every attempt and on a manual resend.
  • webhook-timestamp is the time of sending in Unix seconds. It is new on every attempt.
  • webhook-signature is v1, followed by a base64 HMAC-SHA256 signature.

The body always has the same four fields. This is the call.initiated event of the first test call:

{
"id": "evt_2nb7kq4xyc8vfr1tlm0pzab3cd",
"type": "call.initiated",
"timestamp": "2026-10-22T08:26:59Z",
"data": {
"uuid": "9a266251-d2a3-44fc-b422-9486ddf880c7",
"direction": "outbound",
"caller_number": "+442079XXXXXX",
"callee_number": "+447700XXXXXX",
"caller_id": null,
"caller_type": null,
"callee_id": null,
"callee_type": "contact",
"contact_id": null,
"deal_id": null,
"company_id": null,
"user_id": 101,
"number_id": 10,
"channel_id": 10,
"channel_type": "number",
"started_at": "2026-10-22T08:26:59Z",
"answered_at": null,
"bridged_at": null,
"ended_at": null,
"call_duration": null,
"first_touch_duration": null,
"team_touch_at": null,
"credited": null,
"hangup_by": null,
"missing_call": null,
"missing_call_reason": null,
"callback_time": null,
"callback_user_id": null,
"callback_cdr_uuid": null,
"voicemail_id": null,
"voicemail_type": null,
"voicemail_url": null,
"has_recording": false,
"record_url": null,
"call_flow": [
{
"action": "init",
"detail": { "id": null, "type": "contact" },
"timestamp": 1792657619
}
]
}
}

data is the same object the API returns for that call. The top-level timestamp is when the event happened. It is not the webhook-timestamp header: the header above is 2026-10-22T08:27:06Z, because that request was the second attempt, sent seven seconds after the event.

What each event carries

A call produces three events. This is the timeline of the first test call, in UTC:

Time Event What data gains
08:26:59 call.initiated uuid, direction, caller_number, callee_number, started_at, and the first call_flow entry (init)
08:27:00 call.connected A bridge entry in call_flow with the agent (detail.type is user)
08:27:19 call.ended answered_at, bridged_at, ended_at, call_duration, first_touch_duration, hangup_by, missing_call, has_recording, record_url, and a hangup entry in call_flow

Four details are easy to get wrong:

  • answered_at and bridged_at are still null in call.connected. In both outbound test calls, call.connected fired 1 to 2 seconds after the call started, before the customer picked up (6 seconds later in the first call, 3 seconds later in the second). Read the answer time from call.ended.
  • call_duration is ended_at minus started_at, so it includes ringing. The two test calls show 20 and 12 seconds, while the time from answer to hangup was 13 and 7 seconds. Calculate talk time from answered_at and ended_at.
  • has_recording is false until call.ended, and record_url appears only there.
  • call_flow lists the newest step first.

This is call.ended of the same call. Fields that did not change since call.initiated are left out:

{
"id": "evt_4nb9kq6xyc0vfr3tlm2pzab5ef",
"type": "call.ended",
"timestamp": "2026-10-22T08:27:19Z",
"data": {
"uuid": "9a266251-d2a3-44fc-b422-9486ddf880c7",
"caller_id": 101,
"caller_type": "user",
"answered_at": "2026-10-22T08:27:06Z",
"bridged_at": "2026-10-22T08:27:06Z",
"ended_at": "2026-10-22T08:27:19Z",
"call_duration": 20,
"first_touch_duration": 7,
"credited": false,
"hangup_by": "user",
"missing_call": false,
"has_recording": true,
"record_url": "https://storage.hipcall.com/recordings/...&X-Amz-Expires=604800&X-Amz-Signature=...",
"call_flow": [
{ "action": "hangup", "detail": { "hangup_by": "user" }, "timestamp": 1792657639 },
{ "action": "bridge", "detail": { "id": 101, "type": "user" }, "timestamp": 1792657620 },
{ "action": "init", "detail": { "id": null, "type": "contact" }, "timestamp": 1792657619 }
]
}
}

The panel offers ten events in total. Besides the three call events above, you can subscribe to call.callback_requested, contact.created, contact.number_updated, company.created, company.number_updated, deal.created, and task.created. They use the same four-field body, and data is the object the API returns for that record. This article tests the call events only.

Making it reliable

Three properties of Webhook v2 shape the receiver. Every request is signed, the same event can arrive more than once, and Hipcall does not promise any order. Hipcall waits up to 30 seconds for an answer and counts any 2xx response as delivered.

flowchart TD
    A["POST from Hipcall"] --> B{"Signature valid and timestamp within 5 minutes?"}
    B -- "No" --> C["Reply 401"]
    B -- "Yes" --> D{"webhook-id already handled?"}
    D -- "Yes" --> E["Reply 200, do nothing"]
    D -- "No" --> F["Merge into the record for data.uuid"]
    F --> G["Reply 200"]
    F -.-> H["Background: download the recording"]
    I["Nightly job: compare the API with your records"] -.-> F

Verify the signature before you parse the body

  1. Read the raw body bytes. Do not serialize parsed JSON again, because any change in whitespace breaks the signature.
  2. Build the signed text: {webhook-id}.{webhook-timestamp}.{body}.
  3. Compute an HMAC-SHA256 of that text. The key is the base64-decoded part of the secret after whsec_.
  4. Encode the result in base64 and compare it with each v1, value in the webhook-signature header, using a constant-time comparison. Accept the request if any value matches. During a secret rotation the header holds two values separated by a space.
  5. Reject the request with 401 if webhook-timestamp is more than 5 minutes away from your clock.

Check the timestamp in the header, not the one in the body. A retry carries a new header timestamp, so a delivery that comes back minutes or days later still passes. In the test, the retried events arrived about five minutes after the first attempts and were accepted.

A secret path in the URL and an IP allowlist are no longer needed. The signature already proves that Hipcall sent the request and that nobody changed it.

Answer fast, work later

Store the event, return 2xx, and do slow work afterwards. The receiver in this article also writes to a JSON file in its project, and it answered in 5 to 33 ms in the tests. The recording download runs in a background task.

If your server is overloaded, return 429 with a retry-after header and Hipcall slows down. If the endpoint is gone for good, return 410 and Hipcall turns the webhook off.

Skip repeated deliveries, keep one record per call

Two identifiers do two different jobs:

Identifier Identifies Use it to
webhook-id (the id field in the body) One event Skip a delivery you already handled
data.uuid One call Keep one record for all events of a call

Retries and manual resends keep the webhook-id. In the test, the three events of the first call failed twice with 404 and arrived on the third attempt. They kept their IDs, and the receiver still created one record for the call.

Mark an ID as handled in the same database transaction that writes the record. The example below keeps IDs in memory and marks them before it processes the event. That is fine for a demo, but an event is lost if the process crashes between the two steps.

Do not depend on arrival order

A failed call.initiated can arrive after a call.ended that succeeded the first time. Two rules keep the record correct:

  • Order events by the timestamp in the body, which is when the event happened. Break ties with the event order: call.initiated, then call.connected, then call.ended.
  • Merge fields instead of overwriting them. call.initiated carries null for fields that call.ended fills in, so a late early-event must not erase them.

Keep recordings out of your database

Warning: record_url expires after 7 days, and anyone who has the link can listen to the call. Do not save the link and plan to use it later.

The link points to temporary storage and carries its signature in the query string (X-Amz-Expires=604800). Download the file when the event arrives, store it yourself, and save its path in your database. Try the download a few times with short delays, in case the file is not ready yet.

A resend creates a fresh link. In the test, the call.ended delivery that was retried five minutes late carried a link signed at the time of the retry (X-Amz-Date=20261022T083254Z), although the call ended at 08:27:19Z.

Recover what you missed

A delivery that fails all 10 attempts stays Not delivered. Open the Deliveries tab and select Resend failed to resend all failed deliveries in a time range, optionally for one event type. A resend keeps the webhook-id, so your duplicate check handles it.

Also run a nightly job that compares the API with your records and fills the gaps. Query the API with the date range of the previous day:

curl -sS -H "Authorization: Bearer $HIPCALL_API_TOKEN" \
"https://use.hipcall.com/api/v3/calls?started_at%5Bgte%5D=2026-10-21T00:00:00Z&started_at%5Blte%5D=2026-10-21T23:59:59Z&limit=100"

Compare the uuid values with your database and add the calls you do not have.

Minimal API receiver example

The web project template turns on implicit usings, so the using lines below are all you need. The example keeps calls in memory. Replace the dictionary with your database.

using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
var secret = Environment.GetEnvironmentVariable("HIPCALL_WEBHOOK_SECRET")
?? throw new InvalidOperationException("HIPCALL_WEBHOOK_SECRET is not set.");
var signingKey = Convert.FromBase64String(secret.StartsWith("whsec_") ? secret["whsec_".Length..] : secret);
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(options => options.ListenAnyIP(5080));
var app = builder.Build();
var jsonOptions = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
PropertyNameCaseInsensitive = true
};
var seenDeliveries = new ConcurrentDictionary<string, bool>();
var calls = new Dictionary<string, CallRecord>();
var callsLock = new object();
var http = new HttpClient();
var eventOrder = new Dictionary<string, int>
{
["call.initiated"] = 1,
["call.connected"] = 2,
["call.ended"] = 3
};
app.MapPost("/hipcall/events", async (HttpRequest request) =>
{
using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
var body = buffer.ToArray();
var webhookId = request.Headers["webhook-id"].ToString();
var webhookTimestamp = request.Headers["webhook-timestamp"].ToString();
var webhookSignature = request.Headers["webhook-signature"].ToString();
if (!IsValidSignature(signingKey, webhookId, webhookTimestamp, body, webhookSignature))
{
return Results.Unauthorized();
}
if (!seenDeliveries.TryAdd(webhookId, true))
{
return Results.Ok();
}
var hook = JsonSerializer.Deserialize<WebhookEvent>(body, jsonOptions);
if (hook?.Type is null || !eventOrder.TryGetValue(hook.Type, out var rank)
|| hook.Data.ValueKind != JsonValueKind.Object)
{
Console.WriteLine($"Ignored {hook?.Type ?? "unknown"} ({webhookId})");
return Results.Ok();
}
var data = hook.Data.Deserialize<CallData>(jsonOptions);
if (data?.Uuid is null)
{
return Results.Ok();
}
lock (callsLock)
{
if (!calls.TryGetValue(data.Uuid, out var call))
{
call = new CallRecord { Uuid = data.Uuid };
calls[data.Uuid] = call;
}
call.Direction = data.Direction ?? call.Direction;
call.CallDuration = data.CallDuration ?? call.CallDuration;
call.HangupBy = data.HangupBy ?? call.HangupBy;
call.HasRecording = data.HasRecording ?? call.HasRecording;
call.StartedAt = data.StartedAt ?? call.StartedAt;
call.AnsweredAt = data.AnsweredAt ?? call.AnsweredAt;
call.EndedAt = data.EndedAt ?? call.EndedAt;
var incoming = (hook.Timestamp ?? DateTimeOffset.MinValue, rank);
var current = (call.LastEventAt ?? DateTimeOffset.MinValue,
call.LastEvent is not null ? eventOrder[call.LastEvent] : 0);
if (incoming.CompareTo(current) >= 0)
{
call.LastEvent = hook.Type;
call.LastEventAt = hook.Timestamp;
}
Console.WriteLine($"{hook.Type} -> call {data.Uuid} (last event: {call.LastEvent})");
}
if (!string.IsNullOrEmpty(data.RecordUrl))
{
_ = Task.Run(() => DownloadRecordingAsync(data.Uuid, data.RecordUrl));
}
return Results.Ok();
});
app.Run();
async Task DownloadRecordingAsync(string uuid, string url)
{
for (var attempt = 1; attempt <= 3; attempt++)
{
await Task.Delay(TimeSpan.FromSeconds(3));
using var response = await http.GetAsync(url);
if (response.IsSuccessStatusCode)
{
Directory.CreateDirectory("recordings");
await using var file = File.Create(Path.Combine("recordings", $"{uuid}.mp3"));
await response.Content.CopyToAsync(file);
Console.WriteLine($"Recording saved for call {uuid}");
return;
}
}
Console.WriteLine($"Recording for call {uuid} was not ready after 3 attempts.");
}
static bool IsValidSignature(byte[] key, string id, string timestamp, byte[] body, string signatureHeader)
{
if (id.Length == 0 || !long.TryParse(timestamp, out var seconds))
{
return false;
}
var age = DateTimeOffset.UtcNow - DateTimeOffset.FromUnixTimeSeconds(seconds);
if (age.Duration() > TimeSpan.FromMinutes(5))
{
return false;
}
var signedText = Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(body).ToArray();
var expected = HMACSHA256.HashData(key, signedText);
foreach (var part in signatureHeader.Split(' ', StringSplitOptions.RemoveEmptyEntries))
{
var pieces = part.Split(',', 2);
if (pieces.Length != 2 || pieces[0] != "v1")
{
continue;
}
try
{
if (CryptographicOperations.FixedTimeEquals(Convert.FromBase64String(pieces[1]), expected))
{
return true;
}
}
catch (FormatException)
{
}
}
return false;
}
record WebhookEvent(string? Id, string? Type, DateTimeOffset? Timestamp, JsonElement Data);
record CallData(
string? Uuid,
string? Direction,
int? CallDuration,
string? HangupBy,
bool? HasRecording,
string? RecordUrl,
DateTimeOffset? StartedAt,
DateTimeOffset? AnsweredAt,
DateTimeOffset? EndedAt);
class CallRecord
{
public required string Uuid { get; init; }
public string? Direction { get; set; }
public int? CallDuration { get; set; }
public string? HangupBy { get; set; }
public bool? HasRecording { get; set; }
public DateTimeOffset? StartedAt { get; set; }
public DateTimeOffset? AnsweredAt { get; set; }
public DateTimeOffset? EndedAt { get; set; }
public string? LastEvent { get; set; }
public DateTimeOffset? LastEventAt { get; set; }
}

Run it with the secret in the environment:

dotnet run

Select Send test event in the panel. The receiver prints Ignored webhook.test, and the Deliveries tab shows the delivery as Delivered. After a real call, the console shows one line per event:

call.initiated -> call 9a266251-d2a3-44fc-b422-9486ddf880c7 (last event: call.initiated)
call.connected -> call 9a266251-d2a3-44fc-b422-9486ddf880c7 (last event: call.connected)
call.ended -> call 9a266251-d2a3-44fc-b422-9486ddf880c7 (last event: call.ended)
Recording saved for call 9a266251-d2a3-44fc-b422-9486ddf880c7

To see a rejected request, send one with a wrong signature. The receiver answers 401 with an empty body:

curl -i -X POST http://localhost:5080/hipcall/events \
-H "content-type: application/json" \
-H "webhook-id: evt_local_test" \
-H "webhook-timestamp: $(date +%s)" \
-H "webhook-signature: v1,AAAA" \
-d '{"id":"evt_local_test","type":"webhook.test","timestamp":"2026-10-22T08:00:00Z","data":{}}'

When it fails

A delivery counts as failed when your server answers with anything other than 2xx, does not answer within 30 seconds, or cannot be reached. Hipcall then retries, as described after the table.

Last response Likely cause Response body What to do
404 The webhook URL points to a path the receiver does not serve Empty (content-length: 0) Fix the URL on the General tab. The next scheduled attempt delivers the event, or select Resend
401 Your receiver rejected the signature Empty Check that the receiver uses the secret of this webhook, reads the raw body, and has a correct clock. A rotated secret stops working for old signatures after 24 hours
500 An unhandled error in your code Depends on your code Read the exception log, fix it, then resend. The event is not lost while attempts remain
502 The tunnel or server in front of the receiver is not running Depends on the proxy Start the receiver and the tunnel
429, 502, 504 The server is overloaded Depends on your code Hipcall slows down and follows retry-after when you send it
410 You told Hipcall the endpoint is gone Empty Hipcall turns the webhook off. Create a new webhook if the endpoint comes back

Example: a wrong path

At first, the webhook in the test pointed to a path the receiver did not serve. The first attempt of each event of the first call failed with 404, and so did the second attempt seven seconds later. The Deliveries tab showed this:

webhook-id Event Status Attempt Last response
evt_4nb9kq6xyc0vfr3tlm2pzab5ef call.ended Will retry 2/10 404
evt_3nb8kq5xyc9vfr2tlm1pzab4de call.connected Will retry 2/10 404
evt_2nb7kq4xyc8vfr1tlm0pzab3cd call.initiated Will retry 2/10 404

After the receiver was fixed, the third attempts arrived about five minutes later, in the original order, and all three returned 200. The delivery page of an event lists every attempt with its time, result, duration, and error type.

Retry schedule

Hipcall makes up to 10 attempts. The first one is immediate, then the waits between attempts are 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 14 hours, 20 hours, and 24 hours, which adds up to about 3 days. After the last attempt, the delivery stays Not delivered, and the people who manage developer settings get an email. You get at most one email per webhook per day. You also get an email if an endpoint is turned off.

A webhook.test event is not retried. In the test, two test events that reached a stopped receiver stayed Not delivered with 0 of 10 attempts and no next attempt.

Find out what happened

The Deliveries tab lists every event of the last 30 days with its webhook-id, status, attempt count, last response, and next attempt. You can search by webhook-id and filter by event, time range, and status (All, Delivered, Will retry, Not delivered).

Hipcall always keeps the request and the response of failed attempts. For successful ones it keeps only the status and the duration. If you need the bodies of successful deliveries too, use the button in the Detailed logging card. It keeps them for 2 hours. Turning it off deletes nothing.

Resend

Resend on a delivery page makes one extra attempt and does not change the retry schedule. The delivery goes out with the same webhook-id, so your receiver can skip it if it already has the event, and the recording link is created again at send time. Resend failed on the Deliveries tab does the same for every failed delivery in a time range that you choose.

Parameter reference

Request headers

Header Example Description
webhook-id evt_2nb7kq4xyc8vfr1tlm0pzab3cd Event ID. Same on every attempt and resend.
webhook-timestamp 1792657626 Send time in Unix seconds. New on every attempt.
webhook-signature v1,g3qmK3e9... One or more v1, signatures separated by spaces.
content-type application/json The body is always JSON.
user-agent Hipcall-Webhooks/1.0 Identifies Hipcall as the sender.

Body

Field Type Example Description
id string "evt_2nb7kq4xyc8vfr1tlm0pzab3cd" Event ID. Equal to the webhook-id header.
type string "call.ended" Event type.
timestamp string "2026-10-22T08:27:19Z" When the event happened, in UTC.
data object The object the API returns for the record.

Call fields in data

Field Type Example Description
uuid string "9a266251-d2a3-44fc-b422-9486ddf880c7" Call ID. Same in all events of a call.
direction string "outbound" "inbound" or "outbound".
caller_number string "+442079XXXXXX" Calling number.
callee_number string "+447700XXXXXX" Called number.
started_at string "2026-10-22T08:26:59Z" When the call started, in UTC.
answered_at string or null "2026-10-22T08:27:06Z" When the customer answered. Set in call.ended.
bridged_at string or null "2026-10-22T08:27:06Z" When the two sides were connected. Set in call.ended.
ended_at string or null "2026-10-22T08:27:19Z" When the call ended.
call_duration integer or null 20 Seconds from started_at to ended_at, ringing included.
first_touch_duration integer or null 7 Seconds from started_at to answered_at.
hangup_by string or null "user" Who hung up.
missing_call boolean or null false true for an unanswered call.
has_recording boolean true true when the call has a recording. Sent even if recording links are off.
record_url string or null "https://storage.hipcall.com/..." Temporary listening link, valid for 7 days. Empty if recording links are off.
call_flow array Steps of the call, newest first. Each step has action, detail, and a Unix timestamp.

Next steps

  • Put a queue such as RabbitMQ between the HTTP receiver and the workers that write to your database.
  • Move storage to PostgreSQL with unique indexes on webhook_id and uuid.
  • Schedule the nightly comparison with GET /api/v3/calls.
  • Add handlers for contact.created, company.created, deal.created, and task.created.
  • Ask questions in the Hipcall Community.

To see real-world use cases of the Hipcall API step by step, check out the other example scenarios:

Was this article helpful?