API & Verification

Webhooks & Verification Gate

Every delivered output passes automated post-processing verification before delivery and billing. Configure webhooks for reliable async notifications.

Webhook event types#

Configure a default webhook URL in console.splixir.com (or pass callbackUrl per job). Payloads have the shape { id, event, timestamp, data: JobResponse }.

EventTriggerBilled?Description
job.deliveredTerminal successYes (exact cost)Output passed all verification checks and was delivered to destination or ephemeral R2 URL.
job.failedTerminal failure$0.00Processing or verification failed. Reservation is released and costMicros is 0.
job.rejectedPre-flight rejection$0.00Input failed pre-flight probe (corrupt file, unsupported format, or exceeded limits).

VerificationReport breakdown#

Every delivered job includes a verificationReport comparing the probed input against the probed output, plus per-stage timings and a SHA-256 checksum.

VerificationReportjson
{
  "verified": true,
  "engine": "libvips-8.15",
  "inputProbe": {
    "width": 3000,
    "height": 2000,
    "format": "jpeg",
    "bytes": 1240500,
    "hasExif": true,
    "colorSpace": "srgb"
  },
  "outputProbe": {
    "width": 1200,
    "height": 800,
    "format": "webp",
    "bytes": 86420,
    "exifStripped": true,
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "checks": [
    { "name": "format_match", "passed": true, "detail": "webp" },
    { "name": "dimensions_match", "passed": true, "detail": "1200x800" },
    { "name": "exif_stripped", "passed": true }
  ],
  "timingsMs": {
    "probe": 15,
    "download": 84,
    "transform": 59,
    "verify": 12,
    "upload": 38,
    "total": 208
  }
}

Error classification#

ClassRetryable?Billed?Description
CUSTOMER_FAULTfalse$0.00Unreachable input URL, 404/403 from origin, corrupt image bytes, or exceeded 50 MiB / 100 MP limits.
VERIFY_FAILEDfalse$0.00Output dimensions, format, or metadata checks did not match the requested operations.
INFRA_FAILUREtrue$0.00Transient worker or network fault. Safe to retry with the same idempotencyKey.

Retry schedule#

Your webhook endpoint must respond with a 2xx HTTP status within 10 seconds. Non-2xx responses or timeouts are retried with exponential backoff (up to 5 attempts: 10s, 30s, 2m, 10m, 30m). Delivery attempts are logged in the Console.

HMAC-SHA256 verification#

Every webhook request includes an X-Splixir-Signature header containing the hex-encoded HMAC-SHA256 digest of the raw request body signed with your webhook secret (whsec_...). Always verify using constant-time comparison:

verify-webhook.tstypescript
import crypto from "node:crypto";

export function verifySplixirSignature(
  rawBody: string,
  signatureHeader: string | null,
  webhookSecret: string,
): boolean {
  if (!signatureHeader) return false;
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(rawBody, "utf8")
    .digest("hex");

  const provided = signatureHeader.replace(/^sha256=/, "");
  if (provided.length !== expected.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(provided, "hex"),
    Buffer.from(expected, "hex"),
  );
}