Webhooks

Receive real-time notifications when your videos are ready instead of polling the API.

Setting Up Webhooks

Include a webhookUrl in your production request:

{
  "canvas": { ... },
  "webhookUrl": "https://yourapp.com/webhooks/stratakit"
}

Webhook Events

production.completed

Sent when video rendering finishes successfully:

production.completed

13 linesjson

{
  "event": "production.completed",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "production_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "output_url": "https://assets.stratakit.io/...(presigned URL)",
    "error": null,

production.failed

Sent when video rendering fails:

production.failed

13 linesjson

{
  "event": "production.failed",
  "timestamp": "2026-01-15T10:30:05Z",
  "data": {
    "production_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "output_url": null,
    "error": "Invalid video format: unsupported codec",

Webhook Headers

All webhook requests include the following headers:

•Content-Type: application/json
•User-Agent: StrataKit-Webhook/1.0
•X-StrataKit-Production-Id - The production ID
•X-StrataKit-Delivery - Delivery attempt number (1 for first attempt)

Verifying Webhooks

User-configurable webhook secrets with HMAC-SHA256 signature verification are coming soon. In the meantime, we recommend verifying webhooks by checking the X-StrataKit-Production-Id header against your known production IDs and confirming the payload structure matches the expected format.

Handling Webhooks

Node.js / Express.js

Express.js webhook handler

19 linesjavascript

1 // Express.js example
2 app.post('/webhooks/stratakit', express.json(), (req, res) => {
3   const event = req.body;
4   const productionId = req.headers['x-stratakit-production-id'];
5 
6   switch (event.event) {
7     case 'production.completed':
8       console.log('Video ready:', event.data.output_url);

Python / Flask

Flask webhook handler

18 linespython

1 from flask import Flask, request
2 
3 app = Flask(__name__)
4 
5 @app.route('/webhooks/stratakit', methods=['POST'])
6 def handle_webhook():
7     event = request.get_json()
8     production_id = request.headers.get('X-StrataKit-Production-Id')

Next.js API Route

app/api/webhooks/stratakit/route.ts

20 linestypescript

1 import { NextRequest, NextResponse } from 'next/server';
2 
3 export async function POST(request: NextRequest) {
4   const event = await request.json();
5   const productionId = request.headers.get('x-stratakit-production-id');
6 
7   switch (event.event) {
8     case 'production.completed':

Best Practices

•Respond quickly - Return 200 within 30 seconds, do heavy processing async
•Handle duplicates - We may retry failed deliveries, use idempotent processing
•Use HTTPS - Required for webhook URLs in production
•Validate production IDs - Check the X-StrataKit-Production-Id header matches your records
•Log everything - Store webhook payloads for debugging
•Process async - Queue heavy work instead of blocking the response

Retry Policy

If your endpoint returns a non-2xx status or times out, we'll retry with exponential backoff:

Attempt	Delay
1	Immediate
2	After 1 second
3	After 5 seconds
4	After 30 seconds
5	After 2 minutes
6	After 10 minutes

After 5 failed retries (6 total attempts), we stop retrying and the webhook is marked as failed.

Testing Webhooks Locally

Use a tunneling tool like ngrok to test webhooks during development:

Terminal

bash

# Start your local server
npm run dev

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook URL
# Example: https://abc123.ngrok-free.app/api/webhooks/stratakit

Webhooks

Receive real-time notifications when your videos are ready instead of polling the API.

Setting Up Webhooks

Include a webhookUrl in your production request:

{
  "canvas": { ... },
  "webhookUrl": "https://yourapp.com/webhooks/stratakit"
}

Webhook Events

production.completed

Sent when video rendering finishes successfully:

production.completed

13 linesjson

{
  "event": "production.completed",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "production_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "output_url": "https://assets.stratakit.io/...(presigned URL)",
    "error": null,

production.failed

Sent when video rendering fails:

production.failed

13 linesjson

{
  "event": "production.failed",
  "timestamp": "2026-01-15T10:30:05Z",
  "data": {
    "production_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "output_url": null,
    "error": "Invalid video format: unsupported codec",

Webhook Headers

All webhook requests include the following headers:

•Content-Type: application/json
•User-Agent: StrataKit-Webhook/1.0
•X-StrataKit-Production-Id - The production ID
•X-StrataKit-Delivery - Delivery attempt number (1 for first attempt)

Verifying Webhooks

Handling Webhooks

Node.js / Express.js

Express.js webhook handler

19 linesjavascript

1 // Express.js example
2 app.post('/webhooks/stratakit', express.json(), (req, res) => {
3   const event = req.body;
4   const productionId = req.headers['x-stratakit-production-id'];
5 
6   switch (event.event) {
7     case 'production.completed':
8       console.log('Video ready:', event.data.output_url);

Python / Flask

Flask webhook handler

18 linespython

1 from flask import Flask, request
2 
3 app = Flask(__name__)
4 
5 @app.route('/webhooks/stratakit', methods=['POST'])
6 def handle_webhook():
7     event = request.get_json()
8     production_id = request.headers.get('X-StrataKit-Production-Id')

Next.js API Route

app/api/webhooks/stratakit/route.ts

20 linestypescript

1 import { NextRequest, NextResponse } from 'next/server';
2 
3 export async function POST(request: NextRequest) {
4   const event = await request.json();
5   const productionId = request.headers.get('x-stratakit-production-id');
6 
7   switch (event.event) {
8     case 'production.completed':

Best Practices

•Respond quickly - Return 200 within 30 seconds, do heavy processing async
•Handle duplicates - We may retry failed deliveries, use idempotent processing
•Use HTTPS - Required for webhook URLs in production
•Validate production IDs - Check the X-StrataKit-Production-Id header matches your records
•Log everything - Store webhook payloads for debugging
•Process async - Queue heavy work instead of blocking the response

Retry Policy

If your endpoint returns a non-2xx status or times out, we'll retry with exponential backoff:

Attempt	Delay
1	Immediate
2	After 1 second
3	After 5 seconds
4	After 30 seconds
5	After 2 minutes
6	After 10 minutes

After 5 failed retries (6 total attempts), we stop retrying and the webhook is marked as failed.

Testing Webhooks Locally

Use a tunneling tool like ngrok to test webhooks during development:

Terminal

bash

# Start your local server
npm run dev

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook URL
# Example: https://abc123.ngrok-free.app/api/webhooks/stratakit

1	// Express.js example
2	app.post('/webhooks/stratakit', express.json(), (req, res) => {
3	const event = req.body;
4	const productionId = req.headers['x-stratakit-production-id'];
5
6	switch (event.event) {
7	case 'production.completed':
8	console.log('Video ready:', event.data.output_url);

1	from flask import Flask, request
2
3	app = Flask(__name__)
4
5	@app.route('/webhooks/stratakit', methods=['POST'])
6	def handle_webhook():
7	event = request.get_json()
8	production_id = request.headers.get('X-StrataKit-Production-Id')

1	import { NextRequest, NextResponse } from 'next/server';
2
3	export async function POST(request: NextRequest) {
4	const event = await request.json();
5	const productionId = request.headers.get('x-stratakit-production-id');
6
7	switch (event.event) {
8	case 'production.completed':