Automatic notifications with webhooks

A webhook is an automatic HTTP POST from Uppic to your URL when something happens in your account — no API polling needed.

Supported events

• ✓image.uploaded — an image was uploaded to your account
• ✓optimization.completed — an optimization job finished
• ✓optimization.failed — an optimization job failed
• ✓subscription.changed — the account's plan changed

Register an endpoint

1. 1Go to Dashboard → Webhooks and add an endpoint (must be a public HTTPS URL)
2. 2Choose the events you want to receive
3. 3Save the endpoint's secret for signature verification

{
  "event": "optimization.completed",
  "createdAt": "2026-08-07T12:00:00.000Z",
  "data": { "jobId": "…", "fileCount": 3 }
}

Verify the signature (important)

Every request carries an X-Uppic-Event header (the event name) and X-Uppic-Signature — an HMAC-SHA256 of the raw body, signed with your endpoint secret. Always verify before processing.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Retries and auto-disable

• ✓Respond with HTTP 2xx within 10 seconds to acknowledge
• ✓Failed deliveries retry up to 5 times with exponential backoff
• ✓An endpoint failing 10 times in a row is auto-disabled — re-enable it from the dashboard