Webhooks

Webhooks let your backend react to generation task updates without polling. skills.video sends signed POST requests to your configured endpoint when a generation task is created, starts running, completes, fails, or is canceled. Webhook delivery is at least once. Your handler must verify the signature, reject replayed requests, and process events idempotently.

Configure Endpoints

Configure webhook endpoints from the developer dashboard: https://skills.video/dashboard/developer Use the dashboard to manage endpoint URLs, event filters, enablement, test deliveries, and secret rotation. Store the signing secret in server-side secret storage when it is shown. Do not place the webhook secret in frontend code, mobile apps, logs, or public repositories. Each endpoint is scoped to a workspace and event filter. It only receives events for the selected workspace and selected task lifecycle events.

When Webhooks Are Sent

Webhooks are emitted for generation tasks created through:

POST /api/v1/generation/:provider/:model+

Each webhook endpoint is scoped to a workspace. It only receives events for tasks in that workspace and only for event types enabled on that endpoint.

Event Types

Supported event types:

Event	Meaning
`task.created`	A generation task was accepted and queued.
`task.started`	The worker started processing the task.
`task.completed`	The task finished successfully.
`task.failed`	The task failed.
`task.canceled`	The task was canceled.

Terminal events are task.completed, task.failed, and task.canceled. Once your local task record reaches a terminal state, do not let an older non-terminal event move it backward. Webhook event names describe lifecycle transitions. prediction.state and prediction.status describe the current task state in the payload.

Webhook event	`prediction.state`	Terminal
`task.created`	`queued`	No
`task.started`	`running`	No
`task.completed`	`succeeded`	Yes
`task.failed`	`failed`	Yes
`task.canceled`	`canceled`	Yes

Use the event name to decide which handler branch to run. Use prediction.state to update your local task record.

Delivery Format

Your endpoint receives an HTTP POST request with a JSON body.

POST /webhooks/skills-video HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: evt_2f8f5c2e1c9f4db19e7e4b3d8a1f7caa
webhook-timestamp: 1777370400
webhook-signature: v1,<base64_hmac_sha256>
X-Webhook-Signature: v1=<hex_hmac_sha256>
X-Webhook-Timestamp: 1777370400
X-Webhook-Event-Id: evt_2f8f5c2e1c9f4db19e7e4b3d8a1f7caa
X-Webhook-Event-Type: task.completed

Headers:

Header	Description
`webhook-id`	Standard Webhooks event id. Use this as your primary idempotency key.
`webhook-timestamp`	Standard Webhooks Unix timestamp in seconds. Used for replay protection and signature verification.
`webhook-signature`	Standard Webhooks signature in the format `v1,<base64>`. Recommended for new integrations.
`X-Webhook-Signature`	Legacy v1 HMAC signature in the format `v1=<hex>`. Kept for backward compatibility.
`X-Webhook-Timestamp`	Legacy v1 timestamp. Same value as `webhook-timestamp`.
`X-Webhook-Event-Id`	Legacy v1 event id. Same value as `webhook-id`.
`X-Webhook-Event-Type`	Event type, such as `task.completed`.
`Content-Type`	Always `application/json`.

Example body:

{
  "event": "task.completed",
  "prediction": {
    "id": "TASK_DOCUMENT_ID",
    "state": "succeeded",
    "status": "succeeded",
    "input": {
      "prompt": "sunrise over mountains in watercolor style"
    },
    "template": null,
    "error": null,
    "logs": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "started_at": "2026-01-01T00:00:01.000Z",
    "completed_at": "2026-01-01T00:00:10.000Z",
    "workspace": "WORKSPACE_DOCUMENT_ID",
    "owner": {
      "id": 1,
      "email": "user@example.com",
      "name": "User",
      "avatar": "https://example.com/avatar.png"
    },
    "artifacts": [
      {
        "documentId": "ARTIFACT_DOCUMENT_ID",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "state": "succeeded",
        "type": "image",
        "provider": "google",
        "model": "nano-banana",
        "duration": null,
        "size": null,
        "visibility": "private",
        "tags": [],
        "prompt": "sunrise over mountains in watercolor style",
        "actual_prompt": "sunrise over mountains in watercolor style",
        "resolution": "1080p",
        "aspect_ratio": "9:16",
        "mode": "text-image",
        "like_count": 0,
        "url": "https://example-cdn.com/output.png",
        "asset": {
          "url": "https://example-cdn.com/output.png",
          "name": "output.png",
          "mime": "image/png",
          "width": 1080,
          "height": 1920,
          "formats": {}
        }
      }
    ],
    "credits": {
      "available": 3533,
      "usage": 4
    }
  }
}

For task.failed, prediction.error contains a sanitized error object with code and message. Raw provider errors and internal error details are not included. For task.completed, generated media is usually available in prediction.artifacts and, depending on the model, task output fields returned by the generation result endpoint. Failed task example:

{
  "event": "task.failed",
  "prediction": {
    "id": "TASK_DOCUMENT_ID",
    "state": "failed",
    "status": "failed",
    "input": {
      "prompt": "Turn into a sea of flowers.",
      "duration": 7
    },
    "template": null,
    "error": {
      "code": "VIDEO_GENERATION_TIMEOUT",
      "message": "Generation timed out."
    },
    "logs": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "started_at": "2026-01-01T00:00:01.000Z",
    "completed_at": "2026-01-01T00:00:10.000Z",
    "workspace": "WORKSPACE_DOCUMENT_ID",
    "owner": null,
    "artifacts": [],
    "credits": {
      "available": 3533,
      "usage": 0
    }
  }
}

Payload Field Reference

Common fields:

Field	Type	Description
`event`	`string`	Webhook event type, such as `task.completed`.
`prediction.id`	`string`	Task document id. Use this to correlate with generation results.
`prediction.state`	`string`	Current task state: `queued`, `running`, `succeeded`, `failed`, or `canceled`.
`prediction.status`	`string`	Same state value as `prediction.state`.
`prediction.input`	`object`	Normalized model input that was used for the task.
`prediction.template`	`object \| null`	Template metadata when the task was created from a template.
`prediction.error`	`object \| null`	Sanitized error details for failed tasks, usually with `code` and `message`.
`prediction.logs`	`any \| null`	Provider or worker logs when available.
`prediction.created_at`	`string \| null`	Task creation timestamp.
`prediction.started_at`	`string \| null`	Worker start timestamp.
`prediction.completed_at`	`string \| null`	Terminal timestamp for completed, failed, or canceled tasks.
`prediction.workspace`	`string \| null`	Workspace document id.
`prediction.owner`	`object \| null`	Basic owner profile for the task.
`prediction.artifacts`	`object[]`	Generated assets associated with the task.
`prediction.credits.available`	`number`	Remaining available credits after the task update.
`prediction.credits.usage`	`number`	Credits used by the task.

Artifact fields vary by model and media type, but commonly include documentId, state, type, provider, model, prompt, actual_prompt, resolution, aspect_ratio, url, and asset.

Signature Algorithm

Each webhook endpoint has a secret. Store it on your server and use it to verify every incoming webhook before parsing or processing the JSON payload. New integrations should use the Standard Webhooks v2 headers. Legacy v1 X-Webhook-* headers are still sent for backward compatibility with existing receivers.

Standard Webhooks v2

skills.video sends Standard Webhooks-compatible headers:

webhook-id: <event_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1,<base64_hmac_sha256>

The v2 signature is computed from the event id, timestamp, and exact raw request body:

signed_payload = webhook_id + "." + webhook_timestamp + "." + raw_body
webhook-signature = "v1," + base64(hmac_sha256(base64_decode(webhook_secret_without_whsec_prefix), signed_payload))

Use the official verifier when possible:

npm install standardwebhooks

Express example:

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const webhook = new Webhook(process.env.SKILLS_VIDEO_WEBHOOK_SECRET!);

app.post(
  "/webhooks/skills-video",
  express.raw({ type: "application/json", limit: "2mb" }),
  async (req, res) => {
    const rawBody = req.body.toString("utf8");
    let event: unknown;

    try {
      event = webhook.verify(rawBody, {
        "webhook-id": req.header("webhook-id")!,
        "webhook-timestamp": req.header("webhook-timestamp")!,
        "webhook-signature": req.header("webhook-signature")!
      });
    } catch {
      return res.status(401).json({ error: "invalid_signature" });
    }

    const eventType =
      req.header("X-Webhook-Event-Type") ??
      (event as any).event ??
      (event as any).type;

    await handleWebhookEvent({
      eventId: req.header("webhook-id")!,
      eventType,
      payload: event
    });

    return res.status(204).send();
  }
);

The standardwebhooks verifier checks the timestamp tolerance and compares signatures safely. Your route still needs the raw body; do not mount a JSON parser before the webhook route.

Java / Spring Boot Verification

This example verifies Standard Webhooks v2 with JDK crypto APIs. Keep the body as raw bytes and parse JSON only after verification succeeds.

package com.example.webhooks;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SkillsVideoWebhookController {
  private static final long TOLERANCE_SECONDS = 300;
  private static final String WHSEC_PREFIX = "whsec_";

  private final ObjectMapper objectMapper;
  private final String webhookSecret;

  public SkillsVideoWebhookController(
      ObjectMapper objectMapper,
      @Value("${skills.video.webhook-secret}") String webhookSecret) {
    this.objectMapper = objectMapper;
    this.webhookSecret = webhookSecret;
  }

  @PostMapping("/webhooks/skills-video")
  public ResponseEntity<Void> receive(
      @RequestBody byte[] rawBody,
      @RequestHeader(value = "webhook-id", required = false) String webhookId,
      @RequestHeader(value = "webhook-timestamp", required = false) String timestamp,
      @RequestHeader(value = "webhook-signature", required = false) String signatureHeader,
      @RequestHeader(value = "X-Webhook-Event-Type", required = false) String eventType)
      throws Exception {
    boolean valid = verifyStandardWebhook(
        webhookSecret,
        webhookId,
        timestamp,
        signatureHeader,
        rawBody);

    if (!valid) {
      return ResponseEntity.status(401).build();
    }

    JsonNode event = objectMapper.readTree(rawBody);
    String resolvedEventType =
        eventType != null ? eventType : event.path("event").asText(null);

    recordDurableReceipt(webhookId, resolvedEventType, event);
    handleWebhookEvent(webhookId, resolvedEventType, event);

    return ResponseEntity.noContent().build();
  }

  private boolean verifyStandardWebhook(
      String secret,
      String webhookId,
      String timestamp,
      String signatureHeader,
      byte[] rawBody)
      throws Exception {
    if (secret == null || webhookId == null || timestamp == null || signatureHeader == null) {
      return false;
    }

    long requestTime;
    try {
      requestTime = Long.parseLong(timestamp);
    } catch (NumberFormatException ignored) {
      return false;
    }

    long now = Instant.now().getEpochSecond();
    if (Math.abs(now - requestTime) > TOLERANCE_SECONDS) {
      return false;
    }

    String receivedDigestBase64 = parseStandardSignature(signatureHeader);
    if (receivedDigestBase64 == null) {
      return false;
    }

    byte[] receivedDigest;
    try {
      receivedDigest = Base64.getDecoder().decode(receivedDigestBase64);
    } catch (IllegalArgumentException ignored) {
      return false;
    }

    byte[] key;
    try {
      key = decodeStandardSecret(secret);
    } catch (IllegalArgumentException ignored) {
      return false;
    }

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(key, "HmacSHA256"));
    mac.update((webhookId + "." + timestamp + ".").getBytes(StandardCharsets.UTF_8));
    byte[] expectedDigest = mac.doFinal(rawBody);

    return MessageDigest.isEqual(expectedDigest, receivedDigest);
  }

  private String parseStandardSignature(String signatureHeader) {
    for (String part : signatureHeader.trim().split("\\s+")) {
      if (part.startsWith("v1,") && part.length() > 3) {
        return part.substring(3);
      }
    }
    return null;
  }

  private byte[] decodeStandardSecret(String secret) {
    if (!secret.startsWith(WHSEC_PREFIX)) {
      throw new IllegalArgumentException("Webhook secret must start with whsec_");
    }
    return Base64.getDecoder().decode(secret.substring(WHSEC_PREFIX.length()));
  }

  private void recordDurableReceipt(String eventId, String eventType, JsonNode event) {
    // Insert eventId into a table with a unique constraint before side effects.
  }

  private void handleWebhookEvent(String eventId, String eventType, JsonNode event) {
    // Run idempotent business logic after signature verification and durable receipt.
  }
}

Legacy v1 Compatibility

The signature is computed from the timestamp and the exact raw request body:

signed_payload = timestamp + "." + raw_body
signature = "v1=" + hex(hmac_sha256(webhook_secret, signed_payload))

Important details:

Use the value of X-Webhook-Timestamp exactly as received.
Use the raw request body exactly as received. Do not verify against parsed and re-serialized JSON.
Use HMAC-SHA256 with the endpoint secret as the HMAC key.
Compare signatures with a constant-time comparison function.
Reject requests whose timestamp is outside a short tolerance window, such as 5 minutes.
Verify the signature before trusting X-Webhook-Event-Id, X-Webhook-Event-Type, or any body fields.

Legacy v1 Node.js Verification

This example verifies the signature and timestamp. Mount the raw body parser before any JSON parser for the webhook route.

import crypto from "node:crypto";
import express from "express";

const app = express();

function parseSignature(header: string | undefined) {
  if (!header) return null;
  const [version, digest] = header.split("=", 2);
  if (version !== "v1" || !digest || !/^[a-f0-9]{64}$/i.test(digest)) {
    return null;
  }
  return digest;
}

function timingSafeEqualHex(actualHex: string, expectedHex: string) {
  const actual = Buffer.from(actualHex, "hex");
  const expected = Buffer.from(expectedHex, "hex");
  return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
}

function verifyWebhookSignature(options: {
  secret: string;
  timestamp: string | undefined;
  signatureHeader: string | undefined;
  rawBody: string;
  toleranceSeconds?: number;
}) {
  const {
    secret,
    timestamp,
    signatureHeader,
    rawBody,
    toleranceSeconds = 300
  } = options;

  if (!timestamp) return false;

  const requestTime = Number(timestamp);
  if (!Number.isFinite(requestTime)) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - requestTime) > toleranceSeconds) return false;

  const receivedDigest = parseSignature(signatureHeader);
  if (!receivedDigest) return false;

  const signedPayload = `${timestamp}.${rawBody}`;
  const expectedDigest = crypto
    .createHmac("sha256", secret)
    .update(signedPayload, "utf8")
    .digest("hex");

  return timingSafeEqualHex(expectedDigest, receivedDigest);
}

app.post(
  "/webhooks/skills-video",
  express.raw({ type: "application/json", limit: "2mb" }),
  async (req, res) => {
    const rawBody = req.body.toString("utf8");
    const valid = verifyWebhookSignature({
      secret: process.env.SKILLS_VIDEO_WEBHOOK_SECRET!,
      timestamp: req.header("X-Webhook-Timestamp"),
      signatureHeader: req.header("X-Webhook-Signature"),
      rawBody
    });

    if (!valid) {
      return res.status(401).json({ error: "invalid_signature" });
    }

    const event = JSON.parse(rawBody);
    await handleWebhookEvent({
      eventId: req.header("X-Webhook-Event-Id")!,
      eventType: req.header("X-Webhook-Event-Type")!,
      payload: event
    });

    return res.status(204).send();
  }
);

Python Verification

import hashlib
import hmac
import re
import time

SIGNATURE_RE = re.compile(r"^v1=([a-fA-F0-9]{64})$")

def verify_webhook_signature(
    *,
    secret: str,
    timestamp: str | None,
    signature_header: str | None,
    raw_body: bytes,
    tolerance_seconds: int = 300,
) -> bool:
    if not timestamp or not signature_header:
        return False

    try:
        request_time = int(timestamp)
    except ValueError:
        return False

    if abs(int(time.time()) - request_time) > tolerance_seconds:
        return False

    match = SIGNATURE_RE.match(signature_header)
    if not match:
        return False

    received_digest = match.group(1)
    signed_payload = timestamp.encode("utf-8") + b"." + raw_body
    expected_digest = hmac.new(
        secret.encode("utf-8"),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected_digest, received_digest)

Signature Test Vector

Use this fixed example to verify your implementation. The exact raw_body string matters.

secret = whsec_dGVzdF9zZWNyZXRfa2V5
webhook_id = evt_test_123
timestamp = 1777370400
raw_body = {"event":"webhook.test","data":{"message":"hello"}}

Standard Webhooks v2 signed payload:

evt_test_123.1777370400.{"event":"webhook.test","data":{"message":"hello"}}

Expected Standard Webhooks v2 signature:

webhook-signature: v1,TFcCC2CA8KYwWjkvbI+0XLo5fDzKZjBSlHtL1tbFaDE=

Legacy v1 is also sent for existing receivers. Its signed payload is timestamp + "." + raw_body, and the expected legacy signature for the same example is:

X-Webhook-Signature: v1=82e5a76a4cf5455093bf5dd082c73f7e1b8ad759f0eb742d2ce863358552d4b3

Node.js check:

import crypto from "node:crypto";

const secret = "whsec_dGVzdF9zZWNyZXRfa2V5";
const webhookId = "evt_test_123";
const timestamp = "1777370400";
const rawBody = '{"event":"webhook.test","data":{"message":"hello"}}';

const standardKey = Buffer.from(secret.slice("whsec_".length), "base64");
const standardDigest = crypto
  .createHmac("sha256", standardKey)
  .update(`${webhookId}.${timestamp}.${rawBody}`, "utf8")
  .digest("base64");

console.log(`v1,${standardDigest}`);

Java check:

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class WebhookSignatureVector {
  public static void main(String[] args) throws Exception {
    String secret = "whsec_dGVzdF9zZWNyZXRfa2V5";
    String webhookId = "evt_test_123";
    String timestamp = "1777370400";
    String rawBody = "{\"event\":\"webhook.test\",\"data\":{\"message\":\"hello\"}}";

    byte[] key = Base64.getDecoder().decode(secret.substring("whsec_".length()));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(key, "HmacSHA256"));
    byte[] digest = mac.doFinal(
        (webhookId + "." + timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8));

    System.out.println("v1," + Base64.getEncoder().encodeToString(digest));
  }
}

Signature Troubleshooting

Most signature failures come from verifying different bytes than the bytes that were signed.

Symptom	Likely cause	Fix
Signature works locally but fails in production	Proxy, framework, or middleware changed the request body.	Capture the raw body before JSON parsing and verify that exact string.
Signature fails after `JSON.parse` and `JSON.stringify`	Re-serialized JSON changed whitespace or field order.	Verify against raw body only. Parse JSON after signature verification.
Every request fails after secret rotation	Receiver still uses the old secret or only one server was updated.	Deploy the new secret everywhere. During rollout, support both old and new secrets.
Requests fail intermittently with timestamp errors	Server clock drift or too narrow tolerance.	Sync server time with NTP and use a tolerance such as 5 minutes.
Signature header looks malformed	Missing `v1,` prefix or invalid base64 digest for Standard Webhooks v2.	Prefer the `standardwebhooks` verifier and pass the raw body plus `webhook-*` headers.
Duplicate events trigger duplicate work	Event id is not stored before business logic runs.	Insert `webhook-id` with a unique constraint before side effects.

Log enough metadata to debug failures, but never log the webhook secret, full API keys, or sensitive user input.

Replay Protection

Signature verification proves the request was signed with the endpoint secret, but a valid signed request can still be replayed for a short period. Combine timestamp checks with event id deduplication. Recommended checks:

Reject requests with missing or invalid signature headers.
Reject requests whose webhook-timestamp is outside your tolerance window, such as 5 minutes.
Insert webhook-id into a table with a unique constraint before doing any business work.
If the insert conflicts, treat the event as already received and return 2xx.

Webhook deliveries do not include a separate nonce header. Use the timestamp to limit signature lifetime and use webhook-id as the replay and idempotency key. Legacy receivers can use X-Webhook-Timestamp and X-Webhook-Event-Id, which carry the same values. Keep event ids for at least the full retry window. A 24-hour retention period is a practical minimum for most integrations.

Idempotency

Webhook delivery uses an at-least-once model. Your endpoint must assume these cases can happen:

The same event is delivered more than once.
A delivery succeeds in your system, but the HTTP response is lost and skills.video retries.
Events for the same task arrive out of order because older deliveries are retried later.
A terminal event is processed before an older task.created or task.started retry.

Use two layers of idempotency:

Layer	Key	Purpose
Event receipt	`webhook-id`	Prevent processing the same webhook event twice.
Business side effects	`prediction.id + action`	Prevent duplicate actions such as asset import, user notification, order fulfillment, or downstream job creation.

Recommended Tables

CREATE TABLE skills_video_webhook_events (
  event_id TEXT PRIMARY KEY,
  event_type TEXT NOT NULL,
  task_id TEXT,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  payload JSONB NOT NULL
);

CREATE TABLE skills_video_tasks (
  task_id TEXT PRIMARY KEY,
  state TEXT NOT NULL,
  last_event_id TEXT,
  last_event_type TEXT,
  last_event_received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  payload JSONB NOT NULL
);

CREATE TABLE skills_video_task_side_effects (
  task_id TEXT NOT NULL,
  action TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (task_id, action)
);

Processing Flow

Read the raw request body.
Verify webhook-signature and webhook-timestamp.
Parse the JSON body.
Insert webhook-id into skills_video_webhook_events.
If the insert conflicts, return 204 No Content.
Upsert your local task record by prediction.id.
Apply terminal-state protection so older non-terminal events do not overwrite a completed, failed, or canceled task.
Before executing any side effect, insert (prediction.id, action) into skills_video_task_side_effects.
Only run the side effect if that insert succeeds.
Return a 2xx response quickly.

Terminal-state protection example:

const terminalStates = new Set(["succeeded", "failed", "canceled"]);

function shouldApplyTaskState(currentState: string | null, nextState: string) {
  if (!currentState) return true;
  if (terminalStates.has(currentState) && !terminalStates.has(nextState)) {
    return false;
  }
  return true;
}

Side-effect idempotency example:

async function runOnceForTask(taskId: string, action: string, fn: () => Promise<void>) {
  const inserted = await insertTaskSideEffect(taskId, action);
  if (!inserted) return;
  await fn();
}

if (event.event === "task.completed") {
  await runOnceForTask(event.prediction.id, "import_generated_assets", async () => {
    await importGeneratedAssets(event.prediction.artifacts);
  });
}

Responses And Retries

Return any 2xx status code to acknowledge delivery. 204 No Content is recommended. Non-2xx responses, network failures, and timeouts are retried.

Behavior	Value
Delivery timeout	30 seconds
Maximum delivery attempts	5 total attempts
Retry delays after failed attempts	Approximately 1 minute, 5 minutes, 15 minutes, then 1 hour

Recommended response behavior:

Case	Response	Notes
Valid event processed	`204`	Acknowledge quickly.
Duplicate event id	`204`	Duplicate delivery is not an error.
Invalid signature	`401`	Do not parse or process the payload.
Invalid JSON	`400`	Log a short request summary without secrets.
Temporary internal failure	`500`	Let skills.video retry. Keep processing idempotent.
Business record not ready yet	`202` or `204`	Store the event and reconcile asynchronously.

Do not wait for long downloads, media processing, or downstream API calls before responding. Enqueue that work and return 2xx after the event has been durably recorded.

Test Events

Webhook endpoint test deliveries use the same signature headers. Test events have:

{
  "type": "webhook.test",
  "data": {
    "message": "This is a test webhook delivery",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

Your handler can either store test events separately or return 204 after signature verification.

Delivery Logs

Use the developer dashboard to inspect the 20 most recent delivery attempts for a webhook endpoint: https://skills.video/dashboard/developer Delivery log entries contain fields like this:

{
  "eventId": "evt_2f8f5c2e1c9f4db19e7e4b3d8a1f7caa",
  "eventType": "task.completed",
  "taskId": "TASK_DOCUMENT_ID",
  "status": "success",
  "attempts": 1,
  "httpStatus": 204,
  "signatureVersion": "legacy-v1+standard-webhooks-v2",
  "signedPayloadFormat": "v1:timestamp.raw_body; v2:webhook_id.timestamp.raw_body",
  "error": null,
  "nextRetryAt": null,
  "createdAt": "2026-01-01T00:00:10.000Z"
}

Delivery fields:

Field	Description
`id`	Webhook delivery document id.
`eventId`	Unique event id sent in `webhook-id` and `X-Webhook-Event-Id`.
`eventType`	Event type sent in `X-Webhook-Event-Type`.
`taskId`	Related task id when available.
`status`	Delivery state: `pending`, `processing`, `success`, or `failed`.
`attempts`	Number of delivery attempts already made.
`httpStatus`	Last HTTP status returned by your endpoint.
`signatureVersion`	Signing scheme used for that delivery attempt, when recorded. Older logs may be `null`.
`signedPayloadFormat`	Canonical signed payload format used for that delivery attempt, when recorded. Older logs may be `null`.
`error`	Last network or HTTP error summary.
`nextRetryAt`	Next scheduled retry time, if the delivery is pending retry.
`createdAt`	Delivery record creation time.

success means your endpoint returned a 2xx response. failed means the delivery exhausted retries or could not be queued. pending means it is waiting for its next attempt. processing means a worker has claimed the delivery.

Create Request Idempotency

Webhook idempotency is supported through webhook-id on delivered events. Legacy receivers can use the equivalent X-Webhook-Event-Id. Do not rely on Idempotency-Key for generation create requests unless your integration has confirmed support for that header. If your client retries POST /api/v1/generation/..., store the first returned task id and reconcile by that id before retrying from your own backend. This prevents your application from creating duplicate jobs when the first request succeeded but the client connection failed.

Implementation Checklist

Configure one endpoint per destination URL and workspace in the developer dashboard.
Store the endpoint secret in server-side secret storage.
Verify Standard Webhooks v2 signatures with webhook_id + "." + timestamp + "." + raw_body.
Reject timestamps outside your replay window.
Insert webhook-id before running business logic.
Guard terminal task states from older non-terminal retries.
Make side effects idempotent with prediction.id + action.
Return 2xx after durable receipt and process slow work asynchronously.
Use delivery logs to inspect failed attempts and retry timing.

Security Checklist

Accept only POST requests.
Accept only Content-Type: application/json.
Verify signatures before parsing JSON or executing business logic.
Enforce a timestamp tolerance window.
Deduplicate by webhook-id.
Make task-level side effects idempotent.
Put a maximum raw body size on the webhook route.
Store webhook secrets only in server-side secret storage.
Do not log webhook secrets, full signatures, API keys, or sensitive user payloads.
Rotate the webhook secret immediately if exposure is suspected.

Get started

Billing

APIs

Configure Endpoints

When Webhooks Are Sent

Event Types

Delivery Format

Payload Field Reference

Signature Algorithm

Standard Webhooks v2

Java / Spring Boot Verification

Legacy v1 Compatibility

Legacy v1 Node.js Verification

Python Verification

Signature Test Vector

Signature Troubleshooting

Replay Protection

Idempotency

Recommended Tables

Processing Flow

Responses And Retries

Test Events

Delivery Logs

Create Request Idempotency

Implementation Checklist

Security Checklist

​Configure Endpoints

​When Webhooks Are Sent

​Event Types

​Delivery Format

​Payload Field Reference

​Signature Algorithm

​Standard Webhooks v2

​Java / Spring Boot Verification

​Legacy v1 Compatibility

​Legacy v1 Node.js Verification

​Python Verification

​Signature Test Vector

​Signature Troubleshooting

​Replay Protection

​Idempotency

​Recommended Tables

​Processing Flow

​Responses And Retries

​Test Events

​Delivery Logs

​Create Request Idempotency

​Implementation Checklist

​Security Checklist

Configure Endpoints

When Webhooks Are Sent

Event Types

Delivery Format

Payload Field Reference

Signature Algorithm

Standard Webhooks v2

Java / Spring Boot Verification

Legacy v1 Compatibility

Legacy v1 Node.js Verification

Python Verification

Signature Test Vector

Signature Troubleshooting

Replay Protection

Idempotency

Recommended Tables

Processing Flow

Responses And Retries

Test Events

Delivery Logs

Create Request Idempotency

Implementation Checklist

Security Checklist