Webhooks

Receive real-time event notifications for every call lifecycle event, booking, and lead creation.

Setup

1Go to Settings → Webhooks → Add Endpoint
2Enter your HTTPS URL (must be publicly accessible)
3Select which events to subscribe to
4Copy the webhook secret — you'll need it to verify signatures
5Click Save. Talknex sends a test ping to verify connectivity.

Event types

call.started

A call connected. Includes agent ID, caller number, and call ID.

call.ended

Call disconnected. Includes duration, end reason (caller hung up, agent ended, transfer).

transcript.final

Full transcript for a completed call, with speaker labels and timestamps.

sentiment.updated

Sentiment score updated during the call (polled every 30s). Values: positive, neutral, negative.

appointment.booked

An appointment was successfully created via the book_appointment tool.

lead.created

A new contact was created from a call where the caller was not previously in the system.

transfer.initiated

The agent called transfer_to_human. Includes destination number.

recording.ready

Call recording is available at the provided URL (available ~30s after call ends).

Payload structure

// call.ended example
{
  "id": "evt_7xkz9",
  "type": "call.ended",
  "createdAt": "2026-05-05T11:04:22Z",
  "data": {
    "call": {
      "id": "call_9xkz3",
      "agentId": "agent_8f3c",
      "to": "+14155550192",
      "from": "+18005551234",
      "duration": 142,
      "endReason": "caller_hangup",
      "sentiment": "positive",
      "metadata": { "leadId": "lead_4421" }
    }
  }
}

Verifying signatures

Every webhook request includes a Talknex-Signature header. Verify it with your webhook secret to prevent spoofed events.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature.replace('sha256=', ''))
  );
}

// In your webhook handler:
app.post('/webhooks/talknex', (req, res) => {
  const raw = JSON.stringify(req.body);
  const sig = req.headers['talknex-signature'] as string;
  if (!verifyWebhook(raw, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }
  // process event...
  res.sendStatus(200);
});

Retry logic

Talknex retries failed deliveries (non-2xx response or timeout) with exponential backoff:

1st retryImmediately (after 5s timeout)

2nd retry30 seconds

3rd retry5 minutes

4th retry30 minutes

5th retry2 hours — final attempt

After 5 failed attempts, the event is marked as failed. You can replay failed events from the Webhooks dashboard within 7 days.

← REST API Analytics