Webhooks (SDK)

The SDK mirrors the /v1/webhooks API with typed methods and ships a signature verifier for your receiving endpoint.

Register an endpoint

import { Apulodi } from "@apulodi/sdk";

const apulodi = new Apulodi({
  apiKey: process.env.APULODI_API_KEY!,
});

const { webhook, secret } = await apulodi.webhooks.create({
  url: "https://example.com/hooks/apulodi",
  events: ["file.uploaded", "file.deleted"], // omit for ALL events
});

secret is shown exactly once — save it somewhere secure (e.g. your infrastructure's secrets manager). It is the HMAC key used to verify deliveries; it never appears again in API responses.

Manage endpoints

const webhooks = await apulodi.webhooks.list();
const one = await apulodi.webhooks.get("wh_…");
await apulodi.webhooks.delete("wh_…");

Verify deliveries in your endpoint

Every delivery arrives with an APULODI-Signature header of the form t=<unix-seconds>,v1=<hex-hmac-sha256>. Verify it with Apulodi.webhooks.verify before trusting the payload (constant-time, with a 5-minute replay window):

import { Apulodi } from "@apulodi/sdk";

// Inside your route handler (Next.js server route shown):
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("APULODI-Signature") ?? "";
  const secret = process.env.APULODI_WEBHOOK_SECRET!; // the whsec_… you saved

  const valid = Apulodi.webhooks.verify(secret, rawBody, signature);
  if (!valid) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody);
  // event.type === "file.uploaded", event.data.fileId, …
  return new Response("ok", { status: 200 });
}

Respond 2xx quickly (APULODI times out at 10s and retries on failure).

Inspect & redeliver

const deliveries = await apulodi.webhooks.deliveries("wh_…", { limit: 25 });
// deliveries[0].status === "FAILED", .attempts, .lastError, …

await apulodi.webhooks.redeliver("wh_…", "dl_…");

Security

Verify every signature before processing. Reject expired timestamps.
Keep the signing secret server-side — never ship it to browsers.
APULODI never sends your API key, the signing secret, or any other secret in webhook payloads.

← Uploads

Error handling →