Webhooks Quickstart

Webhooks send task and highlight changes to your server. An organization admin registers each destination once, then a task selects it by ID.

Step 1: Expose a Receiver

Your receiver must accept POST requests over public HTTPS. For local development, run it on port 3000 and expose it with ngrok:

ngrok http 3000

Use a route such as https://example.ngrok-free.app/webhooks/narrative. Preserve the exact request body bytes; you will verify them in Step 4.

Step 2: Register the Endpoint

Open Webhooks, select Add endpoint, and choose the events to receive. Only organization owners and admins can view or manage endpoints. Copy both values after creating it:

Endpoint ID — pass this as webhook_id when creating a task.
Signing secret — store it in a secret manager. It is shown once.

Endpoints belong to the organization, not an individual task. Update the registered URL instead of sending a raw URL with every task.

Step 3: Create a Task

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "soccer",
    "webhook_id": "YOUR_WEBHOOK_ID",
    "render_videos": {
      "render_video": "ffmpeg"
    }
  }'

Use an endpoint ID from the same organization as the API key. See Create Task for the full request.

Events

Event	Sent when	REST projection
`task.status.changed`	The task enters a new logical status.	`data.task` matches Get Task Info.
`highlight.created`	A highlight record is created. This does not wait for rendering.	`data.highlight` matches Get Highlight.

One immutable event is created per logical change, not per video orientation or render. Delivery may occur more than once.

{
  "id": "1fd7dc19-78c1-4f3f-92d6-87d7b821a9de",
  "type": "task.status.changed",
  "api_version": "v1",
  "created_at": "2026-08-05T19:42:10Z",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "task": {
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": 1234,
      "srt_url": "srt://example:9000?passphrase=...",
      "task_payload": {
        "sport": "soccer",
        "webhook_id": "YOUR_WEBHOOK_ID"
      },
      "assigned": true,
      "time_remaining_hours": 5.75,
      "task_status": "ready",
      "failure_reason": null
    }
  }
}

Step 4: Verify the Signature

Every delivery includes:

Header	Value
`Narrative-Event-Id`	Stable, signed event ID. Use it for deduplication.
`Narrative-Webhook-Timestamp`	Unix timestamp for this delivery attempt.
`Narrative-Webhook-Signature`	Lowercase hexadecimal HMAC-SHA256.
`Narrative-Delivery-Id`	ID of this endpoint delivery.

The signed input is the event ID, timestamp, and exact raw request body, separated by periods:

HMAC-SHA256(signing_secret, "{event_id}.{timestamp}.{exact_raw_body}")

Reject timestamps more than five minutes from your server clock. Verify before parsing JSON.

const crypto = require('node:crypto')

function verifyWebhook(rawBody, eventId, timestamp, signature, secrets) {
  const sentAt = Number(timestamp)
  if (!eventId || !Number.isSafeInteger(sentAt) || String(sentAt) !== timestamp) return false
  if (Math.abs(Date.now() / 1000 - sentAt) > 300) return false

  const received = Buffer.from(signature || '', 'utf8')
  let valid = false
  for (const secret of secrets) {
    const expected = Buffer.from(crypto.createHmac('sha256', secret)
      .update(Buffer.from(`${eventId}.${timestamp}.`, 'utf8'))
      .update(rawBody)
      .digest('hex'), 'utf8')
    const candidate = Buffer.alloc(expected.length)
    received.copy(candidate, 0, 0, expected.length)
    valid = (received.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected)) || valid
  }
  return valid
}

import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, event_id: str, timestamp: str,
                   signature: str, secrets: list[str]) -> bool:
    if not event_id:
        return False
    try:
        sent_at = int(timestamp)
    except (TypeError, ValueError):
        return False
    if str(sent_at) != timestamp or abs(time.time() - sent_at) > 300:
        return False

    message = event_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    valid = False
    for secret in secrets:
        expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
        valid = hmac.compare_digest(expected, signature or "") or valid
    return valid

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"time"
)

func Verify(rawBody []byte, eventID, timestamp, signature string, secrets []string) bool {
	if eventID == "" {
		return false
	}

	sentAt, err := strconv.ParseInt(timestamp, 10, 64)
	delta := time.Now().Unix() - sentAt
	if err != nil || strconv.FormatInt(sentAt, 10) != timestamp || delta > 300 || delta < -300 {
		return false
	}

	valid := false
	for _, secret := range secrets {
		mac := hmac.New(sha256.New, []byte(secret))
		mac.Write([]byte(eventID))
		mac.Write([]byte("."))
		mac.Write([]byte(timestamp))
		mac.Write([]byte("."))
		mac.Write(rawBody)
		expected := hex.EncodeToString(mac.Sum(nil))
		valid = hmac.Equal([]byte(expected), []byte(signature)) || valid
	}
	return valid
}

Pass both the current and previous signing secrets during a rotation. Remove the previous secret after the delivery retry window.

Never verify a re-serialized JSON body, and never compare signatures with == or ===. Use your language’s constant-time comparison function.

Delivery Semantics

Delivery is at least once. Narrative retries timeouts and non-2xx responses, so return 2xx only after you have accepted the event. Retries keep the same Narrative-Event-Id; store that ID and ignore duplicates. Do not rely on delivery order. Narrative attempts delivery up to eight times over roughly two minutes. Exhausted deliveries enter dead-letter storage and can be replayed operationally with the same event ID.

Introduction

Concepts

Step 1: Expose a Receiver

Step 2: Register the Endpoint

Step 3: Create a Task

Events

Step 4: Verify the Signature

Delivery Semantics

​Step 1: Expose a Receiver

​Step 2: Register the Endpoint

​Step 3: Create a Task

​Events

​Step 4: Verify the Signature

​Delivery Semantics

Step 1: Expose a Receiver

Step 2: Register the Endpoint

Step 3: Create a Task

Events

Step 4: Verify the Signature

Delivery Semantics