Synento docs
Guides

Webhooks guide

Receive HTTP callbacks when Synento sessions are created, started, ended, recorded, exported, or transcribed.

View as Markdown

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 empty
  • session.ended: the last participant left, so the session is empty
  • recording.ready: sent at the same moment as session.ended. The session's streams are the recording, so replay and export can begin from then; there is no processing step to wait for
  • export.completed: an MP4 export finished successfully (sent once per export)
  • transcript.ready: a transcript finished. Its data holds languages (the languages its cues are in) and speech_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>"
}
  • id identifies the event. A retried delivery carries the same id, so use it to drop duplicates.
  • data is currently always an empty object.
  • There is no timestamp in the payload. If you need the session's times, read started_at and ended_at from GET /v1/sessions/{sessionId}.
  • For export.completed, session_id is 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

AspectDetail
Delivery modelBest-effort POST to your endpoint, sent as the event happens. A 2xx response counts as delivered; redirects are not followed.
Timeout5 seconds per attempt
RetryA 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 endpointsAn endpoint is never paused automatically, however often it fails. Pause it yourself if you need to.
Delivery logEvery attempt is recorded: see Deliveries on the Webhooks page in the dashboard, or GET /v1/webhooks/{webhookId}/deliveries
OrderingNot guaranteed. In particular session.ended and recording.ready are sent together and can arrive in either order.

Monitoring and debugging

When testing locally:

  1. Use ngrok or similar to expose your localhost endpoint over https
  2. Register the public URL as the webhook target
  3. Create a session and check your local logs for the session.created webhook

Once verified, switch to a stable production URL.

Operational notes

  1. Always verify signatures. Unverified webhooks could be spoofed.
  2. Respond quickly (200 OK). Process the payload asynchronously; don't block on long operations.
  3. Log all incoming events. Use logs to audit and debug event flows.
  4. Handle idempotency. If an event is delivered twice, your handler should handle it gracefully; deduplicate on the event id.
  5. Expect more than one start/end pair per session. session.started and session.ended repeat if people rejoin a session after it emptied.

On this page