Webhooks

{
  "event": "job.completed",
  "job_id": "job_abcdefghij123456",
  "status": "completed",
  "completed_at": "2026-04-03T12:00:45.000Z",
  "credits_charged": 5
}

"failed_capabilities": [
  {
    "capability": "brands",
    "code": "BRAND_DETECTION_UNAVAILABLE",
    "message": "Brand detection is temporarily unavailable. Please try again."
  }
]

{
  "event": "job.failed",
  "job_id": "job_abcdefghij123456",
  "status": "failed",
  "completed_at": "2026-04-03T12:00:45.000Z",
  "credits_charged": null,
  "error": {
    "code": "VIDEO_TOO_LONG",
    "message": "Video duration 1830s exceeds plan limit of 600s"
  }
}

{
  "event": "job.cancelled",
  "job_id": "job_abcdefghij123456",
  "status": "cancelled",
  "completed_at": "2026-04-03T12:00:20.000Z",
  "credits_charged": 1
}

{
  "event": "job.held",
  "job_id": "job_abcdefghij123456",
  "status": "held",
  "credits_charged": null,
  "reason": "insufficient_credits",
  "credits_needed": 26,
  "balance": 4
}

{
  "event": "batch.completed",
  "batch_id": "batch_abcdefghij123456",
  "status": "completed",
  "total_jobs": 2,
  "completed_count": 2,
  "failed_count": 0,
  "credits_charged": 14,
  "aggregate_results": {
    "aggregate_answers": [
      {
        "query": "Which of these videos shows animals?",
        "answer": "Only \"Me at the zoo\" does: elephants walk behind the speaker.",
        "video_references": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"]
      }
    ],
    "cross_video_summary": "Two short clips; one is filmed at a zoo."
  },
  "completed_at": "2026-04-03T12:04:10.000Z"
}

{
  "event": "batch.paused",
  "batch_id": "batch_abcdefghij123456",
  "status": "paused",
  "rollup": { "total": 10, "pending": 0, "processing": 0, "completed": 4, "held": 6, "failed": 0, "cancelled": 0 },
  "credits_needed_to_resume": 48
}

{
  "event": "follow.match.completed",
  "follow_id": "fol_abc123",
  "creator": {
    "platform": "youtube",
    "handle": "@examplechannel",
    "name": "Example Channel",
    "url": "https://www.youtube.com/@examplechannel"
  },
  "rule_summary": "\"marathon training\"",
  "video": {
    "id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "My first marathon",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
    "published_at": "2026-04-03T11:52:10.000Z"
  },
  "match_reason": "Matched your filters",
  "job_id": "job_abcdefghij123456",
  "credits_charged": 1,
  "question": "Which race was it, and what was the finish time?",
  "answer": "The Berlin Marathon, finished in 3:58:12.",
  "excerpt": "Today I ran my first marathon…",
  "dashboard_url": "https://netraflow.com/your-workspace/jobs/job_abcdefghij123456",
  "completed_at": "2026-04-03T12:00:45.000Z"
}

import crypto from 'node:crypto';

const TOLERANCE_SECONDS = 300;

function verifyWebhook(body, header, secret, now = Date.now()) {
  if (typeof header !== 'string') return false;
  const pairs = header.split(',').map((part) => part.split('='));
  const timestamp = pairs.find(([key]) => key === 't')?.[1];
  const sentAt = Number(timestamp);
  if (!Number.isFinite(sentAt) || Math.abs(now / 1000 - sentAt) > TOLERANCE_SECONDS) return false;

  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex'));
  return pairs.some(([key, value]) => {
    if (key !== 'v1' || !value) return false;
    const given = Buffer.from(value);
    // Length check first: timingSafeEqual throws on a length mismatch, which would
    // turn a malformed request into a 500 instead of the 401 we want.
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

// In your request handler:
const body = await request.text();
const header = request.headers.get('X-NetraFlow-Signature-V2');

if (!verifyWebhook(body, header, WEBHOOK_SECRET)) {
  return new Response('Invalid signature', { status: 401 });
}

// Signature valid and recent — process the event
const event = JSON.parse(body);

import hashlib
import hmac
import json
import time

TOLERANCE_SECONDS = 300

def verify_webhook(body: bytes, header: str | None, secret: str) -> bool:
    if not header:
        return False
    pairs = [part.split("=", 1) for part in header.split(",")]
    timestamp = next((pair[1] for pair in pairs if len(pair) == 2 and pair[0] == "t"), "")
    if not timestamp.isdecimal() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(
        len(pair) == 2 and pair[0] == "v1" and hmac.compare_digest(pair[1].encode(), expected)
        for pair in pairs
    )

# In a Flask view:
body = request.get_data()
if not verify_webhook(body, request.headers.get("X-NetraFlow-Signature-V2"), WEBHOOK_SECRET):
    abort(401)

event = json.loads(body)