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 }.
| Event | Trigger | Billed? | Description |
|---|---|---|---|
job.delivered | Terminal success | Yes (exact cost) | Output passed all verification checks and was delivered to destination or ephemeral R2 URL. |
job.failed | Terminal failure | $0.00 | Processing or verification failed. Reservation is released and costMicros is 0. |
job.rejected | Pre-flight rejection | $0.00 | Input 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.
{
"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#
| Class | Retryable? | Billed? | Description |
|---|---|---|---|
CUSTOMER_FAULT | false | $0.00 | Unreachable input URL, 404/403 from origin, corrupt image bytes, or exceeded 50 MiB / 100 MP limits. |
VERIFY_FAILED | false | $0.00 | Output dimensions, format, or metadata checks did not match the requested operations. |
INFRA_FAILURE | true | $0.00 | Transient 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:
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"),
);
}