Skip to Content
LYNKORIADocs

Webhooks

Receive signed server-to-server events when calls start and end, participants come and go, and messages are sent.

Webhooks let your backend react without polling: update a call log, bill a session, notify offline users of a new message.

Set up an endpoint

  1. In the console, open your project’s Environments tab and enter an Endpoint URL. Production endpoints must use HTTPS on an origin the platform team has approved.
  2. Select Create signing secret and store the whsec_… value in your backend. It is shown once.
  3. Save the environment.

Verify and handle events

Verify the signature against the raw request body, before parsing JSON:

import express from 'express';
import { createLynkoriaServer, WEBHOOK_SIGNATURE_HEADER } from '@lynkoria/server';

const lynkoria = createLynkoriaServer({
  baseUrl: process.env.LYNKORIA_API_URL!,
  serviceKey: process.env.LYNKORIA_SERVICE_KEY!,
  webhookSecret: process.env.LYNKORIA_WEBHOOK_SECRET!, // pass an array during rotation
});

app.post('/webhooks/lynkoria', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = lynkoria.webhooks.verify(req.body.toString('utf8'), req.get(WEBHOOK_SIGNATURE_HEADER));
  } catch {
    return res.sendStatus(400);
  }
  if (await alreadyProcessed(event.id)) return res.sendStatus(200); // at-least-once delivery
  await handle(event);
  res.sendStatus(200);
});

verify checks the HMAC-SHA256 signature with a constant-time comparison and rejects timestamps more than 5 minutes old, which blocks replays.

Payload

{
  "id": "6c1f…",
  "type": "message.created",
  "created_at": "2026-11-12T08:30:00.000Z",
  "project_id": "…",
  "environment_id": "…",
  "data": { "conversationId": "…", "messageId": "…", "senderId": "alice", "seq": 42 }
}

The Lynkoria-Signature header has the form t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>.

TypeWhendata fields
call.startedThe media room startscallId, productCallId, tenantId, startedAt
call.endedThe call endscallId, productCallId, tenantId, reason, endedAt
participant.joinedA device joins a callcallId, productCallId, tenantId, identity, userId, deviceId, at
participant.leftA device leaves or is removedSame as participant.joined
message.createdA message is storedconversationId, productConversationId, tenantId, messageId, senderId, seq

Delivery and retries

  • Delivery is at least once. Store processed ids and ignore repeats.
  • Respond with any 2xx within 10 seconds. Redirects are not followed and count as failures.
  • Failed deliveries retry with exponential backoff (1 minute, 2 minutes, 4 minutes and so on, capped at 24 hours). After 12 attempts the event is dead-lettered.
  • The console’s Webhooks tab lists pending and dead-lettered deliveries with their last error. After fixing your receiver, select Retry on a dead-lettered event.
  • Events are delivered in roughly the order they occurred, but not guaranteed in order. Use seq for messages and timestamps for call events.

Rotate the signing secret

Select Rotate signing secret in the console. Deliveries are signed with the new secret immediately, so deploy it promptly. During the switch, pass both secrets: webhookSecret: [newSecret, oldSecret].

On this page