Webhooks

Deliver channel lifecycle, client event, presence, history, annotation, and push events to your backend.

Webhooks let Sockudo notify your backend about lifecycle and operational events. They are delivered asynchronously and should be idempotent.

Configure

[webhooks]
enabled = true
batching_enabled = true
max_batch_size = 50
flush_interval_ms = 500
timeout_ms = 5000

Validate signatures

Use the raw request body:

app.post("/sockudo/webhooks", rawBodyMiddleware, (req, res) => {
  const webhook = sockudo.webhook({
    rawBody: req.rawBody,
    headers: req.headers,
  });

  if (!webhook.isValid()) {
    return res.status(401).send("invalid");
  }

  for (const event of webhook.getEvents()) {
    handleWebhookEvent(event);
  }

  res.send("ok");
});

Event handling

Webhook handlers should:

deduplicate by event ID or stable business ID
return quickly
enqueue expensive work
tolerate retries
preserve raw payloads for audit when compliance requires it

Presence lifecycle events are:

member_added
member_updated
member_removed

member_updated is emitted for Protocol V2 sockudo:presence_update frames. Its payload includes channel, user_id, and user_info with the latest member data.

Push webhooks

Push provider status callbacks and push lifecycle webhooks are core to operating notifications. Use them to reconcile provider outcomes with Sockudo publish status.

AI Transport and message webhooks

Enable event types per app webhook. AI Transport event types are:

ai_turn_started
ai_turn_ended
ai_cancel_requested
ai_stream_orphaned

Versioned-message and annotation event types are:

message_version_created
annotation_created
annotation_deleted

ai_turn_ended includes reason and optional error_code. ai_stream_orphaned is emitted when the distributed orphan janitor closes a stale streaming message after ai_transport.rollup.orphan_ttl_ms:

{
  "name": "ai_stream_orphaned",
  "channel": "private-ai-chat",
  "message_serial": "00000000000000000001:node:00000000000000000001",
  "reason": "orphan_timeout"
}

message_version_created includes channel, message_serial, version_serial, and action (message.create, message.update, message.delete, or message.append). Annotation webhooks include channel, message_serial, annotation_serial, and annotation_type; delete events also include deleted_annotation_serial.

Typical push events include:

publish accepted
publish dispatched
provider accepted
provider rejected
device token invalidated
scheduled push cancelled
delivery status callback received

Example handler:

function handleWebhookEvent(event: SockudoWebhookEvent) {
  switch (event.name) {
    case "push.publish_failed":
      alertPushFailure(event.data.publish_id, event.data.provider);
      break;
    case "push.device_invalidated":
      deactivateDevice(event.data.device_id);
      break;
    default:
      recordEvent(event);
  }
}

Retry behavior

Return a non-2xx status only when you want Sockudo to retry. If the event is valid but not useful, record it as ignored and return success.

Security

accept webhooks only over HTTPS
validate signature before parsing business logic
rotate tokens with overlap
avoid logging provider tokens or encrypted payloads
rate limit webhook endpoints separately from public API endpoints