Webhooks - Bedrud

Webhooks allow Bedrud to send real-time HTTP callbacks when events occur in your rooms. You can register multiple webhook endpoints, each with its own event subscription and HMAC signing secret.

Access

Webhook management requires superadmin access. Navigate to Settings → Webhooks in the admin dashboard.

Creating a Webhook

Go to Settings → Webhooks in the admin dashboard.
Click Add Webhook.
Enter a Name and the Endpoint URL that will receive the event payloads.
Select the Events to subscribe to.
Optionally provide a custom HMAC Secret (a random secret is generated if omitted).
Click Save.

Event Types

Event	Triggered When	Status
`room.created`	A room is created	Active
`room.ended`	A room is closed or becomes idle (all participants left)	Active
`participant.joined`	A participant enters a room (authenticated or guest)	Active
`recording.completed`	A recording finishes processing and is stored	Planned (reserved)
`ping`	Sent by the admin Test button	Active

Event names are defined in server/internal/models/webhook.go and validated by the admin API.

Delivery Format

Each delivery is an HTTP POST with JSON body:

{
  "event": "room.ended",
  "timestamp": "2026-04-01T12:34:56Z",
  "data": { }
}

Header	Description
`Content-Type`	`application/json`
`X-Bedrud-Signature`	`sha256=<hmac-hex>` of the raw request body
`X-Bedrud-Event`	Event name (same as `event` in the body)
`X-Bedrud-Timestamp`	ISO-8601 UTC timestamp (same as `timestamp` in the body)

Delivery is single-attempt (no retries). Failures (network, timeout, non-2xx) are logged and soft-failed so room lifecycle operations never block on webhooks. Your endpoint should respond within 10 seconds.

Verifying Webhook Signatures

Verify the signature by computing HMAC-SHA256 of the raw request body using your webhook’s secret:

// Node.js example
const crypto = require('crypto')
 
function verifyWebhook(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(body)
  const expected = 'sha256=' + hmac.digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Use the X-Bedrud-Signature header value when comparing.

Rotating Secrets

Webhook secrets can be rotated at any time. Rotation immediately invalidates the old secret — update your receiver before rotating to avoid failed verifications.

Navigate to Settings → Webhooks.
Click the Rotate button next to the webhook.
The new secret is displayed once. Copy it and update your receiver.

Testing Webhooks

Use the Test button in the admin dashboard to send a test event. This sends a ping event to verify connectivity. The response includes the HTTP status code your endpoint returned.

Troubleshooting

Symptom	Likely Cause	Fix
Webhook never fires	Incorrect event selection	Verify the webhook subscribes to the event type (e.g. `room.created`)
Signature verification fails	Wrong header or secret	Use `X-Bedrud-Signature` and the current secret; verify against the raw body
Timeout errors	Endpoint too slow	Respond within 10 seconds
Missed events after rotation	Old secret still cached	Update your receiver before rotating
Events not retried after outage	By design	Webhooks are advisory single-attempt deliveries

Admin Dashboard — UI for managing webhooks
API Reference — Admin webhook endpoints in OpenAPI