Webhooks

A webhook sends an HTTP POST to your server whenever something happens in your project — a session starts or ends, or a companion is created, updated, or deleted. Use webhooks to react in real time instead of polling the API: record usage as sessions close, or update your own records when a companion finishes generating.

Creating a webhook

You create webhooks in the developer dashboard, per project.

Events

Payload format

Every event shares the same envelope. The event itself is in data, under session or companion:

{
  "eventId": "67d67303ec4f8672fefb704952206d48",
  "eventType": "companion.created",
  "timestamp": 1790685304,
  "organizationId": "org_abc123",
  "projectId": "proj_abc123",
  "data": {
    "companion": { }
  }
}

Session events

session.started and session.closed describe the session in data.session:

{
  "eventId": "9f1c2e7a-4b3d-4f6e-8a1b-2c3d4e5f6a7b",
  "eventType": "session.closed",
  "timestamp": 1790690142,
  "organizationId": "org_abc123",
  "projectId": "proj_abc123",
  "data": {
    "session": {
      "id": "sess_xyz789",
      "type": "webrtc",
      "companionId": "comp_abc123",
      "externalClientId": "user_42",
      "createdAt": 1790689801,
      "startedAt": 1790689803,
      "closedAt": 1790690142,
      "reason": "connection_closed"
    }
  }
}

Companion events

companion.created, companion.updated, and companion.deleted describe the companion in data.companion. For companion.deleted, it's the companion as it was before deletion. Companion events cover the companions your project owns, not the Napster stock catalog.

{
  "eventId": "e10b49a2b70d4657d728873dd473874c",
  "eventType": "companion.updated",
  "timestamp": 1790685858,
  "organizationId": "org_abc123",
  "projectId": "proj_abc123",
  "data": {
    "companion": {
      "id": "comp_abc123",
      "firstName": "Maya",
      "lastName": "Bennett",
      "previewUrl": "https://cdn.napster.com/companions/comp_abc123/preview.jpg",
      "videoLoopUrl": "https://cdn.napster.com/companions/comp_abc123/video.mp4",
      "ethnicity": "multiracial",
      "gender": "female",
      "headline": "Helping people find clarity, momentum, and practical next steps.",
      "tags": {},
      "status": "completed",
      "createdAt": 1790685277,
      "externalClientId": null,
      "versions": ["v1"]
    }
  }
}

A new companion sends companion.created with status: "pending", then one companion.updated for each status change as it generates: generationCompleted, readyToUse, and finally completed. You can attach it to an agent from readyToUse; edit it once it's completed.

Verifying requests

Every delivery is signed with your webhook's signing secret. Verify the signature before trusting a request, so you only act on events that come from Napster.

Each request carries an X-Webhook-Signature header: the HMAC-SHA256 of the raw request body, keyed with your signing secret and hex-encoded.

POST /webhooks/napster HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 077820582aecb562633e656670fa842e81a391a0daebaa85f3bf71d39e933b9b

To verify a request, compute the same HMAC over the body you received and compare it to the header:

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

// express.raw keeps the body as the exact bytes Napster signed
app.post("/webhooks/napster", express.raw({ type: "application/json" }), (req, res) => {
  const expected = createHmac("sha256", process.env.NAPSTER_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  const received = req.get("X-Webhook-Signature") ?? "";

  if (
    received.length !== expected.length ||
    !timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  ) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200);
  // Process event.eventType after responding
});

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/webhooks/napster")
def napster_webhook():
    expected = hmac.new(
        os.environ["NAPSTER_WEBHOOK_SECRET"].encode(),
        request.get_data(),
        hashlib.sha256,
    ).hexdigest()
    received = request.headers.get("X-Webhook-Signature", "")

    if not hmac.compare_digest(expected, received):
        abort(401)

    event = request.get_json()
    # Process event["eventType"] after responding
    return "", 200

Handling deliveries

A delivery succeeds when your endpoint responds with any 2xx status within 10 seconds. Any other status, a network error, or a timeout counts as a failed attempt.

A failed attempt is retried up to 3 more times with exponential backoff: about 1, 2, and 4 seconds between attempts. If every attempt fails, the delivery is marked failed and isn't retried again. You can still inspect it in the delivery history.

• Respond quickly with a 2xx status. Do any slow work after you respond, so the delivery isn't treated as failed.
• Expect duplicates. If your endpoint handles a request but responds too late, the retry delivers the same event again. Use eventId to skip events you've already processed.
• Don't rely on order. Use timestamp to order events for the same session or companion.

Delivery history

The dashboard keeps a history of every delivery for each webhook. Open a webhook to see each delivery's event, status, and timestamp. Open a delivery to see the request that was sent — its body and headers — and each attempt, with the response status, body, and latency your endpoint returned. Response bodies are stored up to 4 KB.

Use it to debug your endpoint: if deliveries fail, the response your endpoint returned is recorded on each attempt.

Next steps