Skip to main content
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:
EventMeaning
task.createdA generation task was accepted and queued.
task.startedThe worker started processing the task.
task.completedThe task finished successfully.
task.failedThe task failed.
task.canceledThe 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 eventprediction.stateTerminal
task.createdqueuedNo
task.startedrunningNo
task.completedsucceededYes
task.failedfailedYes
task.canceledcanceledYes
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:
HeaderDescription
webhook-idStandard Webhooks event id. Use this as your primary idempotency key.
webhook-timestampStandard Webhooks Unix timestamp in seconds. Used for replay protection and signature verification.
webhook-signatureStandard Webhooks signature in the format v1,<base64>. Recommended for new integrations.
X-Webhook-SignatureLegacy v1 HMAC signature in the format v1=<hex>. Kept for backward compatibility.
X-Webhook-TimestampLegacy v1 timestamp. Same value as webhook-timestamp.
X-Webhook-Event-IdLegacy v1 event id. Same value as webhook-id.
X-Webhook-Event-TypeEvent type, such as task.completed.
Content-TypeAlways 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:
FieldTypeDescription
eventstringWebhook event type, such as task.completed.
prediction.idstringTask document id. Use this to correlate with generation results.
prediction.statestringCurrent task state: queued, running, succeeded, failed, or canceled.
prediction.statusstringSame state value as prediction.state.
prediction.inputobjectNormalized model input that was used for the task.
prediction.templateobject | nullTemplate metadata when the task was created from a template.
prediction.errorobject | nullSanitized error details for failed tasks, usually with code and message.
prediction.logsany | nullProvider or worker logs when available.
prediction.created_atstring | nullTask creation timestamp.
prediction.started_atstring | nullWorker start timestamp.
prediction.completed_atstring | nullTerminal timestamp for completed, failed, or canceled tasks.
prediction.workspacestring | nullWorkspace document id.
prediction.ownerobject | nullBasic owner profile for the task.
prediction.artifactsobject[]Generated assets associated with the task.
prediction.credits.availablenumberRemaining available credits after the task update.
prediction.credits.usagenumberCredits 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.
SymptomLikely causeFix
Signature works locally but fails in productionProxy, 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.stringifyRe-serialized JSON changed whitespace or field order.Verify against raw body only. Parse JSON after signature verification.
Every request fails after secret rotationReceiver 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 errorsServer clock drift or too narrow tolerance.Sync server time with NTP and use a tolerance such as 5 minutes.
Signature header looks malformedMissing 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 workEvent 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:
  1. Reject requests with missing or invalid signature headers.
  2. Reject requests whose webhook-timestamp is outside your tolerance window, such as 5 minutes.
  3. Insert webhook-id into a table with a unique constraint before doing any business work.
  4. 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:
LayerKeyPurpose
Event receiptwebhook-idPrevent processing the same webhook event twice.
Business side effectsprediction.id + actionPrevent duplicate actions such as asset import, user notification, order fulfillment, or downstream job creation.
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

  1. Read the raw request body.
  2. Verify webhook-signature and webhook-timestamp.
  3. Parse the JSON body.
  4. Insert webhook-id into skills_video_webhook_events.
  5. If the insert conflicts, return 204 No Content.
  6. Upsert your local task record by prediction.id.
  7. Apply terminal-state protection so older non-terminal events do not overwrite a completed, failed, or canceled task.
  8. Before executing any side effect, insert (prediction.id, action) into skills_video_task_side_effects.
  9. Only run the side effect if that insert succeeds.
  10. 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.
BehaviorValue
Delivery timeout30 seconds
Maximum delivery attempts5 total attempts
Retry delays after failed attemptsApproximately 1 minute, 5 minutes, 15 minutes, then 1 hour
Recommended response behavior:
CaseResponseNotes
Valid event processed204Acknowledge quickly.
Duplicate event id204Duplicate delivery is not an error.
Invalid signature401Do not parse or process the payload.
Invalid JSON400Log a short request summary without secrets.
Temporary internal failure500Let skills.video retry. Keep processing idempotent.
Business record not ready yet202 or 204Store 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:
FieldDescription
idWebhook delivery document id.
eventIdUnique event id sent in webhook-id and X-Webhook-Event-Id.
eventTypeEvent type sent in X-Webhook-Event-Type.
taskIdRelated task id when available.
statusDelivery state: pending, processing, success, or failed.
attemptsNumber of delivery attempts already made.
httpStatusLast HTTP status returned by your endpoint.
signatureVersionSigning scheme used for that delivery attempt, when recorded. Older logs may be null.
signedPayloadFormatCanonical signed payload format used for that delivery attempt, when recorded. Older logs may be null.
errorLast network or HTTP error summary.
nextRetryAtNext scheduled retry time, if the delivery is pending retry.
createdAtDelivery 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.