Webhook Events Reference
Complete reference for all webhook event types and their payload structures.
Payload Structure
All webhook payloads follow the same structure:
{
"event": "event.type",
"timestamp": "2026-01-19T02:30:00.000Z",
"data": {
// Event-specific payload
}
}Signature Verification
Verify webhook signatures to ensure requests are from Velora:
| Header | Description |
|---|---|
X-Velora-Signature | HMAC-SHA256 signature of the request body |
X-Velora-Timestamp | Unix timestamp (milliseconds) when the event was sent |
X-Velora-Event | The event type (e.g., stream.online) |
// Node.js signature verification
const crypto = require('crypto');
function verifySignature(body, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
hmac.update(body);
const expectedSignature = hmac.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}Retry Policy
If your endpoint returns a non-2xx status code, Velora will retry delivery:
| Attempt | Delay |
|---|---|
| 1st retry | Immediate |
| 2nd retry | 1 minute |
| 3rd retry | 5 minutes |
| 4th retry | 30 minutes |
| 5th retry | 2 hours |
After 5 failed attempts, the webhook will be automatically disabled. Re-enable it from your dashboard once the issue is resolved.
Best Practices
1.
Respond quickly (under 5 seconds)
Return a 200 status immediately and process the event asynchronously if needed.
2.
Handle duplicate events
Use the event timestamp and type to detect and ignore duplicates during retries.
3.
Always verify signatures
Reject requests with invalid or missing signatures to prevent spoofing.
4.
Use HTTPS endpoints
Webhook URLs must use HTTPS for security. HTTP endpoints will be rejected.