Webhooks

HMAC-signed event delivery with automatic retries.

Creating a Webhook Endpoint

bash
curl -X POST /api/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mediakit",
    "events": ["asset.ready", "asset.failed", "video.transcoded"],
    "active": true
  }'

Or create via the Admin Panel: Sidebar → Webhooks → Create.

Events

EventTriggered When
asset.createdNew asset uploaded
asset.readyAsset processing complete
asset.failedAsset processing failed
asset.deletedAsset removed
video.transcodedVideo transcoding complete
video.transcode_failedVideo transcoding failed

Payload Format

json
{
  "id": "evt_abc123",
  "event": "video.transcoded",
  "timestamp": "2026-03-29T12:00:00Z",
  "data": {
    "asset_id": 1,
    "title": "My Video",
    "status": "ready",
    "hls_url": "https://r2.../videos/1/master.m3u8",
    "duration": 120.5,
    "qualities": ["360p", "480p", "720p", "1080p"]
  }
}

Signature Verification

Every webhook request includes an X-MediaKit-Signature header containing an HMAC-SHA256 signature of the request body:

verify-webhook.ts
import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example:
app.post('/webhooks/mediakit', (req, res) => {
  const signature = req.headers['x-mediakit-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  // Process the event
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Retry Policy

If your endpoint returns a non-2xx status, MediaKit retries with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 30 minutes
  • Attempt 5: After 2 hours

Delivery attempts are visible in the Admin Panel under Webhooks → Deliveries.

← AnalyticsAI Analysis