Webhooks guide
Receive HTTP callbacks when Synento sessions are created, started, ended, recorded, exported, or transcribed.
Synento POSTs JSON to a URL you register.
Events
Synento sends these lifecycle events:
session.created: a session was created (through the API, an SDK, the CLI or an agent)session.started: the first participant joined a session that was emptysession.ended: the last participant left, so the session is emptyrecording.ready: sent at the same moment assession.ended. The session's streams are the recording, so replay and export can begin from then; there is no processing step to wait forexport.completed: an MP4 export finished successfully (sent once per export)transcript.ready: a transcript finished. Itsdataholdslanguages(the languages its cues are in) andspeech_seconds(the speech transcribed so far). Sent again if a later run adds what people said after rejoining
These six are the only event types you can subscribe to; registering any
other name is refused with 400.
session.started and session.ended are sent each time a session fills and
empties, so a session that people leave and rejoin produces more than one pair.
Setting up a webhook receiver
1. Create the webhook endpoint on your server
// Example: Express.js handler
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
// "t=<unix seconds>,v1=<hex>"
const header = req.headers['x-synento-signature-v2'] ?? '';
const { t, v1 = '' } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
// Refuse deliveries signed more than 5 minutes ago: a captured request
// replayed later fails here.
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) {
return res.status(401).send('Stale or missing signature');
}
// Verify HMAC-SHA256 over "<t>.<raw body>", exactly as received
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET)
.update(`${t}.`)
.update(req.body)
.digest('hex');
if (v1.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
const payload = JSON.parse(req.body.toString());
// Dispatch based on event type
switch (payload.type) {
case 'session.created':
console.log('New session:', payload.session_id);
break;
case 'session.started':
console.log('Session started:', payload.session_id);
break;
case 'session.ended':
console.log('Session ended:', payload.session_id);
break;
case 'recording.ready':
console.log('Recording ready:', payload.session_id);
break;
case 'export.completed':
console.log('Export completed:', payload.session_id);
break;
}
res.status(200).send('OK');
});2. Register the webhook with Synento
curl -X POST https://api.synento.com/v1/webhooks \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhook",
"events": ["session.created", "session.started", "session.ended"]
}'The webhook belongs to the API key's project. The response includes the
endpoint's signing secret (whsec_…). Each endpoint has its own secret, so
adding a second endpoint never changes the first one's. It is returned only
this once. Store it where your receiver can read it (YOUR_WEBHOOK_SECRET above):
{ "data": {
"id": "<webhook-id>",
"project_id": "<project-id>",
"url": "https://your-server.com/webhook",
"events": "session.created,session.started,session.ended",
"is_active": true,
"secret": "whsec_…",
"created_at": "…"
}, "error": null }In production the URL must be https and resolve to a public address;
localhost, private and link-local addresses are refused, both when you
register and again when each delivery connects. A project can have up to 20
endpoints. Redirects are not followed, a delivery gives up after 5 seconds,
and only the first 4 KB of your response body is kept for the delivery log. You can also add endpoints from the
Webhooks page in the dashboard.
3. List your webhooks to verify
curl https://api.synento.com/v1/webhooks \
-H "Authorization: Bearer sk_live_xxxxx"The list never includes secrets. events is a comma-separated string.
Change events, pause, resume or delete an endpoint
# Change which events the endpoint receives (replaces the list)
curl -X PATCH https://api.synento.com/v1/webhooks/{webhookId} \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"events": ["session.ended", "recording.ready"]}'
# Pause (false) or resume (true) delivery
curl -X PATCH https://api.synento.com/v1/webhooks/{webhookId} \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"is_active": false}'
# Delete
curl -X DELETE https://api.synento.com/v1/webhooks/{webhookId} \
-H "Authorization: Bearer sk_live_xxxxx"Events that happen while an endpoint is paused are not delivered later.
Webhook payload structure
Each webhook is a POST with Content-Type: application/json and a body like:
{
"data": {},
"id": "<event-uuid>",
"project_id": "<project-id>",
"type": "session.started",
"session_id": "<session-id>"
}ididentifies the event. A retried delivery carries the sameid, so use it to drop duplicates.datais currently always an empty object.- There is no timestamp in the payload. If you need the session's times, read
started_atandended_atfromGET /v1/sessions/{sessionId}. - For
export.completed,session_idis the session that was exported; the payload does not identify the export itself.
The event type is also sent in an X-Synento-Event-Type header.
Signature verification
Every webhook carries two signatures, both HMAC-SHA256 with your webhook's secret key, as lowercase hex:
X-Synento-Signature-V2: t=<unix seconds>,v1=<digest>. The digest of<t>.<raw body>. Use this one: because the time is signed, you can refuse a delivery signed more than a few minutes ago (the example above allows 5), so a request someone captured cannot be replayed to you later.X-Synento-Signature: <digest>. The digest of the raw body alone. It is still sent so existing receivers keep working, but it cannot detect a replay. Move to V2 when you can.
Always verify a signature before processing.
Compute the digest over the raw body bytes exactly as they arrived, not over JSON you have parsed and re-serialised, which will not match, and compare in constant time, as the receiver example above does.
Rotating the signing secret
If a secret may have leaked, or you have lost it, issue a new one from Rotate secret on the Webhooks page, or:
curl -X POST https://api.synento.com/v1/webhooks/{webhookId}/rotate-secret \
-H "Authorization: Bearer sk_live_xxxxx"The response carries the new secret, once. It takes effect immediately and
the old secret stops working. Deliveries your receiver rejects before you have
deployed the new secret are retried for about six minutes (see below), and
retries are signed with the new secret, so deploy it within that window and
nothing is lost. Pausing the endpoint does not help: events that happen
while it is paused are never delivered.
Event delivery and retry
| Aspect | Detail |
|---|---|
| Delivery model | Best-effort POST to your endpoint, sent as the event happens. A 2xx response counts as delivered; redirects are not followed. |
| Timeout | 5 seconds per attempt |
| Retry | A failed delivery (network error, timeout or non-2xx) is attempted up to three more times: a few seconds later, then about 2 minutes and about 4 minutes after that. Pending retries are stored durably and survive a server restart. After the fourth failed attempt the event is dropped. |
| Failing endpoints | An endpoint is never paused automatically, however often it fails. Pause it yourself if you need to. |
| Delivery log | Every attempt is recorded: see Deliveries on the Webhooks page in the dashboard, or GET /v1/webhooks/{webhookId}/deliveries |
| Ordering | Not guaranteed. In particular session.ended and recording.ready are sent together and can arrive in either order. |
Monitoring and debugging
When testing locally:
- Use ngrok or similar to expose your localhost endpoint over https
- Register the public URL as the webhook target
- Create a session and check your local logs for the
session.createdwebhook
Once verified, switch to a stable production URL.
Operational notes
- Always verify signatures. Unverified webhooks could be spoofed.
- Respond quickly (200 OK). Process the payload asynchronously; don't block on long operations.
- Log all incoming events. Use logs to audit and debug event flows.
- Handle idempotency. If an event is delivered twice, your handler should handle it gracefully; deduplicate on the event
id. - Expect more than one start/end pair per session.
session.startedandsession.endedrepeat if people rejoin a session after it emptied.