Webhooks

Uninstall webhooks

When an installation of your extension is uninstalled, Extension Report calls your backend with a signed HTTPS request carrying the installation id and the user id your extension reported. Your backend matches it with its own records to free a licence seat or a device, close a session, or stop emails.

Included on every plan for now, Free included. Signatures follow Standard Webhooks. No SDK change is needed: it uses sdk.getInstallationId(), available in every current version of @extension-report/js.

When it fires, and when it does not

The browser gives an extension no code to run at uninstall. It only opens a URL registered in advance.

The SDK registers one uninstall URL per installation with runtime.setUninstallURL. When the user removes the extension, the browser opens that URL. Extension Report checks the uninstall token it issued to that installation, records the uninstall, and, if the project has an enabled uninstall webhook, queues one installation.uninstalled event for your endpoint.

  • One event per installation: reloading the uninstall page does not send it again.
  • No event when the webhook is paused or removed at that moment, or when the browser never opens the page (see limits).
  • Disabling the extension is not an uninstall and sends nothing.
  • The uninstall URL is visible to the user (address bar, history). Someone who opens it without uninstalling triggers the event for their own installation only. Treat the event as “this installation asked to be released”, not as proof that the extension is gone.

Some uninstalls are never seen. Keep a server-side fallback: release a seat or device that has not checked in with your backend for a period you choose. The webhook is the fast path; the inactivity rule is the safety net.

Set up in the dashboard

Extension → Settings → Uninstall webhook. Project owners only.

  1. Enter the endpoint URL and choose Create webhook. The URL must use https, reach the public internet (no private, loopback, link-local or reserved address, no localhost, .local, .internal, .lan or .home.arpa host), contain no credentials and stay under 2,048 characters. The fragment is dropped. The host is checked again, after DNS resolution, before every delivery.
  2. A signing secret (whsec_...) is generated. Reveal or copy it and store it in your backend's secret manager.
  3. Choose Send test event and check Recent deliveries (the last 10, with status, HTTP code and error).
StatusMeaning
DeliveredYour endpoint answered with a 2xx.
RetryingQueued, or waiting for the next attempt.
FailedTen attempts without a 2xx.
SkippedNot sent: the webhook was paused, or the workspace's plan no longer includes webhooks.
  • Untick the checkbox and save to pause: uninstalls are not queued, and pending retries are skipped.
  • Rotate secret creates a new secret at once. For 24 hours every delivery carries two signatures, one per secret, so your endpoint can switch to the new secret without rejecting anything.
  • Resend sends a finished delivery again (see retries).
  • Clear the URL and save to remove the webhook and its delivery log.

Payload

A POST with a JSON body. Key order is not guaranteed.

installation.uninstalled.json
{
  "id": "srv_9b2f0d6c4a1e8f3b7c5d2a9e6f1b4c8d0a7e3f5b9c2d6a1e8f4b7c3d5a9e2f6b",
  "type": "installation.uninstalled",
  "api_version": "2026-11-20",
  "created_at": "2026-11-20T10:00:01.000Z",
  "project": {
    "id": "cmh2k9x0a0001ab12cd34ef56",
    "public_key": "pk_er_..."
  },
  "data": {
    "installation_id": "2f6c1d3e-9a4b-4c7d-8e2f-1a3b5c7d9e0f",
    "user_id": "usr_8f3a21",
    "uninstalled_at": "2026-11-20T10:00:00.000Z",
    "extension_version": "1.4.79",
    "browser_name": "Chrome",
    "os": "macOS",
    "country": "FR"
  }
}
FieldMeaning
idEvent id, also sent as webhook-id. For an uninstall it is srv_ followed by 64 hex characters, derived from the project and installation: retries, reloads of the uninstall page and manual resends carry the same id. Test events use evt_test_ followed by 24 hex characters, new for each test.
typeinstallation.uninstalled, or webhook.test for a test event.
api_versionVersion of this payload contract: 2026-11-20.
created_atWhen Extension Report built the event (ISO 8601, UTC).
project.idExtension Report project id.
project.public_keyPublic key of the project (pk_er_...), as shipped in the extension.
data.installation_idExtension Report's id for the installation: the value of sdk.getInstallationId() in the extension.
data.user_idThe last user id passed to sdk.identify for this installation, or null.
data.uninstalled_atWhen Extension Report recorded the uninstall, that is the first time the uninstall page was opened (ISO 8601, UTC).
data.extension_versionExtension version carried by the uninstall URL, otherwise the last version seen, or null.
data.browser_nameLast browser name seen for the installation, or null.
data.osLast operating system seen for the installation, or null.
data.countryISO 3166-1 alpha-2 country from the last IP geolocation of the installation, or null.

Ignore fields you do not use: new fields can be added to this version.

Headers

HeaderValue
webhook-idEvent id, same as id in the body. Stable across retries and resends.
webhook-timestampUnix time in seconds when this attempt was signed.
webhook-signatureSpace-separated list of v1,<base64> signatures. Two during the 24 hours after a secret rotation.
Content-Typeapplication/json
User-AgentExtensionReport-Webhooks/1.0 (+https://extension.report/docs/uninstall-webhooks)
X-Extension-Report-EventEvent type, same as type in the body (informative).
X-Extension-Report-DeliveryDelivery id in the Settings log (informative). Not covered by the signature.

Verify the signature

Standard Webhooks: use an official library, or the dozen lines below.

  1. Reject the request if webhook-timestamp is more than 300 seconds away from your clock.
  2. The key is the base64-decoded part of the secret after whsec_.
  3. Compute HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body> and base64-encode it.
  4. Split webhook-signature on spaces. Accept the request if one v1, entry matches, compared in constant time.

Sign the raw bytes you received. A framework that parses JSON before your handler (a JSON body parser, request.json()) gives you an object whose re-serialization does not match. Each attempt is signed again with a new timestamp; the id and the body stay the same.

The Standard Webhooks libraries exist for JavaScript, Python, Go, Ruby, PHP, Java, Rust, C# and more. They take the whsec_ secret as shown in Settings.

route.ts
// app/api/webhooks/extension-report/route.ts (Next.js), with the official library:
// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.EXTENSION_REPORT_WEBHOOK_SECRET!); // whsec_...

type ExtensionReportEvent = {
  id: string;
  type: "installation.uninstalled" | "webhook.test";
  data: { installation_id: string; user_id: string | null };
};

export async function POST(request: Request) {
  // Read the raw body: parsing and re-serializing JSON changes the signed bytes.
  const rawBody = await request.text();
  let event: ExtensionReportEvent;
  try {
    event = webhook.verify(rawBody, Object.fromEntries(request.headers)) as ExtensionReportEvent;
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }
  if (event.type !== "installation.uninstalled") return new Response(null, { status: 204 });

  // One transaction: record event.id (unique) and release the linked device.
  await releaseDeviceOnce({ eventId: event.id, installationId: event.data.installation_id });
  return new Response(null, { status: 204 });
}

releaseDeviceOnce stands for your own data layer. Without a dependency:

verify-extension-report-webhook.ts
// Without a dependency. Same algorithm as the Standard Webhooks libraries.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyExtensionReportWebhook(input: {
  secret: string; // whsec_...
  body: string; // raw request body
  headers: { id: string | null; timestamp: string | null; signature: string | null };
  toleranceSeconds?: number;
}) {
  const { id, timestamp, signature } = input.headers;
  if (!id || !timestamp || !signature) return false;
  const seconds = Number(timestamp);
  if (!Number.isInteger(seconds)) return false;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - seconds) > (input.toleranceSeconds ?? 300)) return false;
  const key = Buffer.from(
    input.secret.startsWith("whsec_") ? input.secret.slice("whsec_".length) : input.secret,
    "base64",
  );
  const expected = createHmac("sha256", key).update(`${id}.${seconds}.${input.body}`).digest();
  return signature.split(" ").some((candidate) => {
    const [version, value] = candidate.split(",", 2);
    if (version !== "v1" || !value) return false;
    const received = Buffer.from(value, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
server.mjs
// Any Node.js server, without a framework.
import { createServer } from "node:http";
import { verifyExtensionReportWebhook } from "./verify-extension-report-webhook.js";

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const body = Buffer.concat(chunks).toString("utf8");
    const valid = verifyExtensionReportWebhook({
      secret: process.env.EXTENSION_REPORT_WEBHOOK_SECRET,
      body,
      headers: {
        id: req.headers["webhook-id"] ?? null,
        timestamp: req.headers["webhook-timestamp"] ?? null,
        signature: req.headers["webhook-signature"] ?? null,
      },
    });
    if (!valid) {
      res.writeHead(400).end();
      return;
    }
    res.writeHead(204).end(); // answer first, then process (deduplicate on webhook-id)
    void handleEvent(JSON.parse(body));
  });
}).listen(3000);

Retries, idempotency and resend

Delivery is at least once.

Any 2xx response is a success. Anything else is retried: another status code, a network error, no response within 10 seconds, or a redirect (redirects are not followed). The response body is ignored.

AttemptSent
1immediately
230 s later
31 min later
42 min later
54 min later
68 min later
716 min later
832 min later
91 h 4 min later
102 h 8 min later (about 4 h 16 min after the first attempt)

After the tenth failure the delivery is marked failed. Deliveries and their payload are kept 30 days; within that time Resend in Settings sends a finished delivery again (delivered, failed or skipped), with the same webhook-id and a new series of up to ten attempts. After 30 days it can no longer be resent: your inactivity fallback covers what was lost.

  • The same event can arrive more than once: your server processed it but answered too late, or someone pressed Resend. Deduplicate on webhook-id (equal to id in the body).
  • Answer quickly with a 2xx and do slow work afterwards, or in the same transaction as the deduplication record.
  • Releasing a device that is already released should do nothing.

Test events

Send test event in Settings, or sendTest through MCP, queues a webhook.test event signed like a real one, even when the webhook is paused. Its installation_id is test-installation, the other data fields are null and uninstalled_at is the current time. It follows the same retry rules and appears in Recent deliveries.

Answer it with a 2xx and do not act on it.

Limits by browser and consent

The webhook only sees uninstalls that reach the uninstall page.

CaseBehaviour
Chrome, Edge and other Chromium browsersSupported. The browser opens the uninstall URL set by the SDK in a new tab.
FirefoxSupported once telemetry may be sent. When the extension declares data collection permissions, the user must grant technicalAndInteraction; until then the SDK sets no uninstall URL.
SafariNot supported. runtime.setUninstallURL exists but has no effect, so no uninstall is ever seen.
Telemetry disabledsdk.setTrackingEnabled(false), initialConsent: "denied" before the user opts in, or unreadable consent: the SDK clears the uninstall URL.
Before the first eventThe uninstall URL needs the uninstall token returned by the first successful event batch. An extension removed before that sends nothing.
Tab never reaches extension.reportOffline machine, blocked network, browser profile deleted with the extension, browser closed before the page loads: the uninstall is never seen.

An extension has one uninstall URL, owned by the SDK. Do not call runtime.setUninstallURL yourself: the last call replaces the SDK's URL, and the webhook stops firing.

For seats, devices or licences, combine the webhook with a server-side inactivity rule (for example, release a device after it has not called your backend for 30 days).

Security checklist

  • Verify the signature on the raw body with a constant-time comparison (or a Standard Webhooks library), and reject a timestamp more than 5 minutes away.
  • Store the installation id only through your authenticated API, on the caller's own record. Never act on an installation id received from anywhere else.
  • Deduplicate on webhook-id; make the release idempotent.
  • Answer with a 2xx quickly; the call times out after 10 seconds.
  • Treat delivery as at least once, and as possibly missing: keep an inactivity fallback.
  • Keep the signing secret in a secret manager, never in the extension, a repository or a prompt. Rotate it if it leaks; the 24-hour overlap avoids downtime.
  • data.user_id is whatever your extension passed to sdk.identify. Do not use it alone to decide what to release.

Configure through MCP or an AI assistant

Two tools on the MCP server.

  • get_uninstall_webhook (analytics:read or setup:write): URL, enabled state, a masked secret preview, the end of a rotation overlap if one is running, and the last 10 deliveries. Never the secret.
  • configure_uninstall_webhook (setup:write, one owned project): arguments projectId, url, enabled, remove, rotateSecret, sendTest. Passing url creates or updates the webhook and enables it unless enabled: false is passed too; enabled alone pauses or resumes; remove: true deletes it. With rotateSecret the result also gives previousSecretValidUntil, the end of the 24-hour overlap.

The signing secret appears in the tool result only when it is created or rotated. The assistant must put it straight into the receiving backend's secret manager, not in the conversation, a file or a commit. Project owners can still reveal it in Settings. list_uninstall_webhook_deliveries reads the 30-day log and redeliver_uninstall_webhook resends a finished delivery, like the Resend button in Settings.

A typical request: “Create the uninstall webhook for project X with URL https://api.example.com/webhooks/extension-report, store the secret in our secret manager, send a test event, then read the deliveries. In the extension, send sdk.getInstallationId() with the licence check and store it on the device.”