Webhooks

Webhook events

Velora delivers 21 event typesto your endpoint, every one of them wrapped in the same envelope and signed with the same header. Below: the envelope, the full catalogue with a real payload for each event, and then the parts you only need once — signature verification, the retry schedule, and what Velora expects your endpoint to do.

The envelope

Every webhook body has the same three top-level keys. event tells you which handler to run, and everything event-specific lives under data— the payloads listed further down are the contents of that field, not the whole body.

Request body
{
  "event": "event.type",
  "timestamp": "2026-01-19T02:30:00.000Z",
  "data": {
    // Event-specific payload
  }
}

Event catalogue

Filter by category, then open an event to read what fires it and see an example datapayload. Example values are illustrative — field names and types are the contract, not the sample content.

Filter

Signature verification

Verify webhook signatures to ensure requests are from Velora. Three headers arrive with every delivery; you need all three to reconstruct the signature.

HeaderDescription
X-Velora-SignatureHMAC-SHA256 signature over timestamp.body, prefixed with sha256=
X-Velora-TimestampUnix timestamp (milliseconds) when the event was sent
X-Velora-EventThe event type (e.g., stream.online)
Node.js — verify a delivery
// Node.js signature verification
// This is the SAME recipe as the main webhooks doc — the signature covers
// "timestamp.body" (X-Velora-Timestamp, a dot, then the raw request body)
// and arrives with a "sha256=" prefix.
const crypto = require('crypto');

function verifySignature(body, timestamp, signature, secret) {
  const sig = signature.replace('sha256=', '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  );
}

Retry policy

If your endpoint returns a non-2xx status code, Velora will retry delivery on this schedule.

AttemptDelay
1st retryImmediate
2nd retry1 minute
3rd retry5 minutes
4th retry30 minutes
5th retry2 hours

After 5 failed attempts, the webhook will be automatically disabled. Re-enable it from your dashboard once the issue is resolved.

What your endpoint should do

Four expectations, in the order they bite you.

  1. 1Respond quickly (under 5 seconds)Return a 200 status immediately and process the event asynchronously if needed.
  2. 2Handle duplicate eventsUse the event timestamp and type to detect and ignore duplicates during retries.
  3. 3Always verify signaturesReject requests with invalid or missing signatures to prevent spoofing.
  4. 4Use HTTPS endpointsWebhook URLs must use HTTPS for security. HTTP endpoints will be rejected.

Next steps