Webhooks

What webhooks do

Webhooks let VideoNest push event notifications to your server in real time. Instead of polling the API to check whether a video has processed or published, your endpoint receives a POST request the moment the event occurs.

Common use cases

• Trigger downstream workflows when a video finishes processing
• Update a CMS record when a video publishes to a distribution partner
• Send internal notifications when distribution errors occur
• Sync VideoNest events with your data warehouse or analytics system

Registering a webhook endpoint

1. Navigate to Settings → Webhooks in your VideoNest dashboard.
2. Click Add Endpoint and enter your server URL (must be publicly reachable over HTTPS).
3. Select the event types you want to receive. You can subscribe to individual events or all events.
4. Save. VideoNest will immediately send a test ping to verify the endpoint is reachable.

Event types

Payload schema

All webhook payloads are JSON and share the same top-level structure:

{
  "event": "video.processed",
  "timestamp": "2026-03-30T10:15:00Z",
  "data": {
    "id": "vid_abc123",
    "title": "My Video Title",
    "status": "ready",
    "duration": 142,
    "channel_id": "ch_abc123"
  }
}

For distribution.completed and distribution.failed, the data object includes feed_id, partner_name, and (on failure) error_code and error_message.

Signature verification

VideoNest signs every webhook request using HMAC-SHA256. The signature is sent in the X-VideoNest-Signature header as a hex digest. Your signing secret is shown in Settings → Webhooks when you create or view an endpoint.

To verify a request, compute the HMAC-SHA256 of the raw request body using your signing secret and compare it to the header value. Reject requests that do not match.

// Node.js example
const crypto = require('crypto');

function verifySignature(rawBody, signingSecret, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Retry behavior

If your endpoint does not respond with a 2xx status within 10 seconds, VideoNest marks the delivery as failed and retries up to 3 times using exponential backoff: after 1 minute, 5 minutes, then 30 minutes. If all retries fail, the event is recorded as undelivered in your webhook log.

Your endpoint should respond with 200 OK as quickly as possible and process the event asynchronously if needed. Returning a 2xx response before completing your handler logic prevents unnecessary retries.

Best practices

• Respond with 200 OK immediately and defer heavy processing to a background queue.
• Store the event id and skip processing if you receive the same event twice (idempotency).
• Validate the X-VideoNest-Signature header on every request before acting on the payload.
• Monitor your webhook log in Settings for failed deliveries and investigate promptly.