Webhooks

Webhooks notify your system when an async job completes.

{
  "webhook": {
    "url": "https://example.com/webhooks/capture",
    "sign": true,
    "errors": true
  }
}

Success payload

{
  "job_id": "123",
  "status": "complete",
  "result_url": "https://api.ssapi.com/v1/jobs/123/result"
}

Error payload

{
  "job_id": "123",
  "status": "error",
  "error": {
    "code": "timeout_error",
    "message": "Job timed out."
  }
}

Signature verification

When webhook.sign is enabled, the API sends X-Signature and X-Timestamp headers.

import crypto from "crypto";

const secret = process.env.WEBHOOK_SECRET as string;
const receivedSignature = req.headers["x-signature"] as string;
const body = req.rawBody; // raw request payload

const expected = crypto
  .createHmac("sha256", secret)
  .update(body)
  .digest("hex");

if (receivedSignature !== expected) {
  throw new Error("Invalid signature");
}

Retries

Webhooks retry on 429 and 5xx responses with exponential backoff. Make your endpoint idempotent.