Webhooks
Receive real-time notifications when jobs complete, fail, or are cancelled.
Webhooks deliver HTTP POST notifications to your server when jobs reach a terminal state. Available on Pro and Enterprise plans.
Events
Prop
Type
Payload
{
"event": "job.completed",
"job_id": "job_abc123",
"status": "completed",
"completed_at": "2026-04-03T12:00:45.000Z",
"credits_charged": 5
}Prop
Type
Setting up webhooks
Pass a webhook_url when creating a job:
curl -X POST https://api.netraflow.com/v1/jobs \
-H "Content-Type: application/json" \
-H "X-Api-Key: sk_live_your_key_here" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"capabilities": ["transcription"],
"webhook_url": "https://your-server.com/webhooks/netraflow"
}'Return 200 OK immediately before processing the payload. The webhook timeout is 5 seconds — if your server does
heavy processing synchronously, you risk unnecessary retries. Acknowledge first, process async.
Signature verification
Webhook requests include an X-NetraFlow-Signature header containing an HMAC-SHA256 signature of the raw JSON body, signed with your webhook secret.
import crypto from 'node:crypto';
function verifyWebhook(body, signature, secret) {
const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
// In your request handler:
const body = await request.text();
const signature = request.headers.get('X-NetraFlow-Signature');
if (!verifyWebhook(body, signature, WEBHOOK_SECRET)) {
return new Response('Invalid signature', { status: 401 });
}
// Signature valid — process the event
const event = JSON.parse(body);Retry strategy
Failed deliveries are retried with exponential backoff:
Prop
Type
Each attempt has a 5-second timeout. A delivery is successful when your server returns any 2xx status code.
Requirements
- HTTPS only — HTTP URLs are rejected at job creation time.
- Private IPs blocked — Webhook URLs resolving to private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are rejected to prevent SSRF.