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
- 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.
- Select Create signing secret and store the
whsec_…value in your backend. It is shown once. - 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>")>.
| Type | When | data fields |
|---|---|---|
call.started | The media room starts | callId, productCallId, tenantId, startedAt |
call.ended | The call ends | callId, productCallId, tenantId, reason, endedAt |
participant.joined | A device joins a call | callId, productCallId, tenantId, identity, userId, deviceId, at |
participant.left | A device leaves or is removed | Same as participant.joined |
message.created | A message is stored | conversationId, productConversationId, tenantId, messageId, senderId, seq |
Delivery and retries
- Delivery is at least once. Store processed
ids and ignore repeats. - Respond with any
2xxwithin 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
seqfor 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].