@certysign/sdk 2.5.0 → 2.5.1

package/README.md

@@ -23,7 +23,11 @@ Official Node.js SDK for **CertySign Trust Services** — hash-based digital sig
   - [client.certificates — X.509 Certificate Management](#clientcertificates--x509-certificate-management)
   - [client.pki — PKI Infrastructure](#clientpki--pki-infrastructure)
   - [client.envelopes — Envelope Management](#clientenvelopes--envelope-management)
-  - [client.legacySign — Legacy Document Signing](#clientlegacysign--legacy-document-signing)
+  - [client.legacySign — Legacy Document Signing](#clientlegacysign--legacy-document-signing)
+    - [client.webhooks — Event Notifications](#clientwebhooks--event-notifications)
+  - [client.billing — Wallet, Quotes and Pricing](#clientbilling--wallet-quotes-and-pricing)
+  - [client.signers — Sponsored Signer Certificates](#clientsigners--sponsored-signer-certificates)
+  - [client.request — Any Endpoint](#clientrequest--any-endpoint)
 - [Complete Examples](#complete-examples)
 - [Error Handling](#error-handling)
 - [Rate Limiting](#rate-limiting)
@@ -1117,6 +1121,272 @@ Legacy methods: `quickSign()`, `batchSign()`, `verifyById()`, `verifyDocument()`
 
 ---
 
+### `client.webhooks` — Event Notifications
+
+Register an endpoint and CertySign calls you when something finishes, instead of you
+asking repeatedly. Requires the `webhook:manage` permission on your API key.
+**Deliveries are not charged**, and neither are the status endpoints.
+
+#### `create({ url, events, description? })` — Register an endpoint
+
+```js
+const { data } = await client.webhooks.create({
+  url: 'https://api.example.com/hooks/certysign',
+  events: ['envelope.completed', 'envelope.declined'],   // omit for all events
+  description: 'Production order pipeline',
+});
+
+// data.secret is returned ONCE and is never readable again. Store it now.
+process.env.CERTYSIGN_WEBHOOK_SECRET = data.secret;
+```
+
+Events: `envelope.sent`, `envelope.viewed`, `envelope.signed` (per signature),
+`envelope.completed`, `envelope.declined`, `envelope.voided`, `envelope.expired`,
+`signing_session.completed`, `sponsorship.created`,
+`sponsorship.certificate_issued`, `sponsorship.verification_rejected`,
+`sponsorship.failed`, `webhook.test`.
+
+#### `list()`, `remove(webhookId)`, `test(webhookId)`
+
+```js
+const { data } = await client.webhooks.list();
+await client.webhooks.test(data.webhooks[0].webhookId);   // sends a webhook.test delivery
+await client.webhooks.remove(data.webhooks[0].webhookId);
+```
+
+#### `deliveries({ webhookId?, status?, limit? })`, `redeliver(deliveryId)`
+
+```js
+// What did we send, and what did your endpoint say?
+const { data } = await client.webhooks.deliveries({ status: 'failed', limit: 50 });
+for (const d of data.deliveries) {
+  console.log(d.event, d.responseStatus, d.error);
+  await client.webhooks.redeliver(d.deliveryId);
+}
+```
+
+#### Verifying the signature
+
+Use the built-in helper. It is timing-safe, enforces a freshness window, and reports
+the two mistakes that otherwise fail silently — signing the body alone (which leaves a
+captured delivery replayable forever) and verifying after `JSON.parse` (which changes
+the bytes the signature covers).
+
+```js
+const { CertySignClient } = require('@certysign/sdk');
+
+// express.raw, NOT express.json — the signature covers the bytes as sent.
+app.post('/hooks/certysign', express.raw({ type: 'application/json' }), (req, res) => {
+  const { valid, reason, event } = CertySignClient.verifyWebhookSignature({
+    secret: process.env.CERTYSIGN_WEBHOOK_SECRET,
+    headers: req.headers,
+    rawBody: req.body,          // Buffer or string, never a parsed object
+    toleranceSeconds: 300,      // default
+  });
+
+  if (!valid) return res.status(401).send(reason);
+
+  if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+  handle(event);
+  res.sendStatus(200);          // answer fast; do the work afterwards
+});
+```
+
+If you would rather implement it yourself: the signature is HMAC-SHA256 over
+`"<timestamp>.<raw body>"` — **not the body alone** — compared timing-safely, over the
+raw bytes, before any JSON parsing.
+
+```js
+const crypto = require('crypto');
+
+// express.raw, NOT express.json — the signature covers the bytes as sent.
+app.post('/hooks/certysign', express.raw({ type: 'application/json' }), (req, res) => {
+  const ts  = req.get('X-CertySign-Timestamp');
+  const sig = (req.get('X-CertySign-Signature') || '').replace('sha256=', '');
+
+  // Reject anything older than 5 minutes.
+  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
+
+  const expected = crypto
+    .createHmac('sha256', process.env.CERTYSIGN_WEBHOOK_SECRET)
+    .update(ts + '.' + req.body.toString())
+    .digest('hex');
+
+  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
+    return res.sendStatus(401);
+  }
+
+  const event = JSON.parse(req.body.toString());
+  if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+
+  handle(event);
+  res.sendStatus(200);   // answer fast; do the work afterwards
+});
+```
+
+#### Delivery, retries and duplicates
+
+- Respond **2xx** quickly. Anything else counts as a failure.
+- Retries on network errors, timeouts and 5xx: 10s, 1m, 5m, 30m, 2h, then stop.
+- A **4xx other than 429 is not retried** — your endpoint rejected the shape, and the
+  same bytes would be rejected again.
+- Delivery is **at-least-once**. De-duplicate on `eventId`, which is stable across
+  retries and redeliveries.
+- After 20 consecutive failures the webhook is disabled and the reason recorded.
+
+**Webhooks do not replace polling.** A delivery you never received is unrecoverable
+unless you can ask for the current state, so the status endpoints remain — and they
+are free to call.
+
+---
+
+### `client.billing` — Wallet, Quotes and Pricing
+
+Read-only, and every call here is free — checking a balance must never itself cost
+money.
+
+#### `wallet()` — Token balance and standing
+
+```js
+const { data } = await client.billing.wallet();
+console.log(`${data.availableBalance} ${data.currency} available`);
+```
+
+Spend against **`availableBalance`**, not `balance`: `balance` includes tokens already
+reserved by operations in flight. A `status` of `'suspended'` means chargeable calls
+are refused even when the balance looks healthy, so check it before concluding you can
+afford something.
+
+#### `quote({ operationType, operationSubType?, quantity?, additionalSigners? })`
+
+What an operation will cost, and whether you can currently cover it. Call it **before**
+a large batch: one answer up front beats `INSUFFICIENT_BALANCE` halfway through, with
+some documents signed and charged and the rest not.
+
+```js
+const { data } = await client.billing.quote({
+  operationType: 'document_signing',      // or 'certificate_issuance'
+  operationSubType: 'ADVANCED',           // e.g. 'ADVANCED', 'ADES'
+  quantity: documents.length,
+});
+
+if (!data.canAfford) {
+  throw new Error(`Need ${data.tokensTotal}, have ${data.availableBalance}`);
+}
+```
+
+#### `transactions({ limit?, skip?, type?, status? })`, `plan()`, `pricing()`
+
+```js
+const { data } = await client.billing.transactions({ limit: 100, type: 'debit' });
+const { data: plan } = await client.billing.plan();       // your tier and its limits
+const { data: rates } = await client.billing.pricing();   // the full price list
+```
+
+---
+
+### `client.signers` — Sponsored Signer Certificates
+
+A person cannot sign until they hold a certificate. These let you pay for one on their
+behalf and watch it become usable, instead of discovering at signing time that it is
+not there.
+
+#### `signingStatus(email, { issueCompletionUrl? })` — Can this person sign yet?
+
+Requires `cert:status`. Free to call, so it is safe in front of every send.
+
+```js
+const { data } = await client.signers.signingStatus('jane@example.com');
+
+if (!data.canSign) {
+  // data.reason is NO_SIGNING_CERTIFICATE or AWAITING_IDENTITY_VERIFICATION
+  console.log(data.reason);
+}
+```
+
+Worth calling **before** a batch: it turns a per-document failure — discovered halfway
+through, after the wallet has been charged — into one answer up front.
+
+For someone stuck at `AWAITING_IDENTITY_VERIFICATION`, ask for a link you can redirect
+them to, so they need not hunt for the invitation email:
+
+```js
+const { data } = await client.signers.signingStatus(email, { issueCompletionUrl: true });
+if (data.pendingSponsorship?.completionUrl) {
+  return redirect(data.pendingSponsorship.completionUrl);
+}
+```
+
+`issueCompletionUrl` **mints a new link and the previous one stops working**, including
+the one already in their inbox. Ask for it when you are about to redirect someone, not
+on every poll. It needs `signer:sponsor`, because minting an onboarding credential is
+the same class of act as sponsoring one.
+
+#### `sponsor({ email, name?, tier?, restrictToSponsor? })` — Pay for their certificate
+
+Requires `signer:sponsor`, a paid plan and a funded wallet.
+
+```js
+const { data } = await client.signers.sponsor({
+  email: 'jane@example.com',
+  name: 'Jane Mwangi',        // shown on the invitation; the certificate carries the
+                              // name on their verified ID
+  tier: 'ades',               // 'ses' | 'ades' (default) | 'qes'
+  restrictToSponsor: true,    // only signs your documents (default)
+});
+
+return redirect(data.completionUrl);
+```
+
+They **cannot sign when this returns** — `status` is `awaiting_member` until they
+complete identity verification. Subscribe to `sponsorship.certificate_issued` rather
+than polling for it.
+
+This also makes them a **member of your organisation** once the certificate issues:
+they get an account, appear in your member list, and their certificate falls under your
+governance.
+
+`restrictToSponsor: false` gives them a certificate usable anywhere, including with
+your competitors. That is a deliberate choice, not a default.
+
+#### `resendSetup(email)` — Send the setup link again
+
+```js
+await client.signers.resendSetup('jane@example.com');
+```
+
+**This rotates the token**, which invalidates the link in any email already sent. That
+is the point — an old link that still works is an old link someone else can use — but
+it does mean the earlier email stops working the moment you call this.
+
+---
+
+### `client.request` — Any Endpoint
+
+The API can gain an endpoint at any time. This calls one that has no typed method yet,
+so you are never blocked waiting for an SDK release.
+
+```js
+const res = await client.request('POST', '/sdk/v1/some-new-endpoint', {
+  data: { foo: 'bar' },
+  params: { verbose: true },      // query string
+  idempotencyKey: 'batch-2026-10-01',
+});
+```
+
+Authentication, retries, idempotency-conflict handling, the error shape and the
+User-Agent all behave exactly as they do for a typed resource. The only thing you give
+up is the named method and its documentation.
+
+Prefer a typed resource where one exists — it records the shape and keeps working if a
+path changes. Use this when there is no resource yet.
+
+> New response fields need nothing at all: responses are passed through untouched, so
+> a field added server-side is readable immediately on whatever version you have
+> installed.
+
+---
+
 ## Complete Examples
 
 ### PDF: PAdES Sign with signCallback (Recommended)
@@ -1387,6 +1657,14 @@ For batch workloads, use `batchHashAndSign()` or `batchSignHashes()` to sign up
 
 ## Migration from v1
 
+### What's New in v2.5.1
+
+- **`client.webhooks`** — register an endpoint and be told when envelopes and
+  sponsorships change state, instead of polling. See
+  [client.webhooks](#clientwebhooks--event-notifications).
+- The `User-Agent` now reports the real package version. It had been pinned at
+  `1.0.0` for the whole 2.x line, so server logs could not tell SDK versions apart.
+
 ### What's New in v2.2.0
 
 | Feature | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certysign/sdk",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Official Node.js SDK for CertySign — hash-based digital signing, X.509 certificates, and PKI services. Documents never leave your system.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "test": "jest --coverage",
     "lint": "eslint src/**/*.js",
-    "build:types": "npx tsc --emitDeclarationOnly"
+    "build:types": "npx tsc --emitDeclarationOnly",
+    "test:durability": "node test/durability.test.js"
   },
   "keywords": [
     "certysign",

package/src/index.js

@@ -28,6 +28,7 @@ const { DashboardResource }       = require('./lib/DashboardResource');
 const { IdentityResource }        = require('./lib/IdentityResource');
 const { BillingResource }         = require('./lib/BillingResource');
 const { SignerResource }          = require('./lib/SignerResource');
+const { WebhookResource }         = require('./lib/WebhookResource');
 const { DocumentHasher }          = require('./lib/DocumentHasher');
 const { SignatureEmbedder }       = require('./lib/SignatureEmbedder');
 
@@ -124,6 +125,7 @@ class CertySignClient {
     this.identity     = new IdentityResource(this._http);       // National-ID verification (IPRS)
     this.billing      = new BillingResource(this._http);        // Balance, quotes, plan (read-only)
     this.signers      = new SignerResource(this._http);         // Sponsor + check the people you sign for
+    this.webhooks     = new WebhookResource(this._http);        // Be told, instead of polling
     this.hasher       = new DocumentHasher();                   // Local document hashing
 
     // TSA URL: explicit > environment-derived
@@ -194,6 +196,147 @@ class CertySignClient {
       return { ok: false, environment: this.environment, error: err.message, code: err.code };
     }
   }
+
+  /**
+   * Call any CertySign endpoint, including ones this SDK version has no method for.
+   *
+   * This exists so the backend can ship an endpoint and you can use it the same
+   * day, without waiting for an SDK release. Everything a typed resource gives you
+   * still applies: authentication, retries, idempotency-conflict handling, the
+   * error shape and the User-Agent. The only thing you give up is the named
+   * method and its JSDoc.
+   *
+   * Prefer a typed resource where one exists — it documents the shape and will keep
+   * working if a path changes. Reach for this when there is no resource yet.
+   *
+   * @param {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'} method
+   * @param {string} path                     e.g. '/sdk/v1/some-new-endpoint'
+   * @param {object} [options]
+   * @param {object} [options.data]           JSON body
+   * @param {object} [options.params]         query string
+   * @param {object} [options.headers]        extra headers
+   * @param {string} [options.idempotencyKey]
+   * @returns {Promise<any>} the parsed response body
+   *
+   * @example
+   * // An endpoint added to the API after this SDK was published:
+   * const res = await client.request('POST', '/sdk/v1/envelopes/bulk-void', {
+   *   data: { envelopeIds: ids, reason: 'duplicate batch' },
+   * });
+   */
+  request(method, path, options = {}) {
+    if (!method) throw new Error('client.request: method is required (GET, POST, PUT, PATCH, DELETE)');
+    if (!path)   throw new Error('client.request: path is required (e.g. "/sdk/v1/...")');
+    if (!String(path).startsWith('/')) {
+      throw new Error(`client.request: path must start with "/" — got "${path}"`);
+    }
+    return this._http.request(String(method).toUpperCase(), path, options);
+  }
+
+  /**
+   * Verify an incoming webhook delivery.
+   *
+   * Every integrator otherwise hand-writes this, and the two ways to get it wrong
+   * both fail silently rather than loudly:
+   *
+   *   - signing the body alone instead of `timestamp + "." + body`, which leaves a
+   *     captured delivery replayable forever; and
+   *   - verifying after `JSON.parse`, because re-serialising changes the bytes the
+   *     signature was computed over.
+   *
+   * So pass the RAW body: a Buffer or the original string, never a parsed object.
+   * With Express that means `express.raw({ type: 'application/json' })`, not
+   * `express.json()`.
+   *
+   * Comparison is timing-safe, and a delivery older than `toleranceSeconds` is
+   * rejected even when the signature is good.
+   *
+   * @param {object} opts
+   * @param {string} opts.secret                  the whsec_... shown once at creation
+   * @param {object} opts.headers                 the request headers (case-insensitive)
+   * @param {Buffer|string} opts.rawBody          the body exactly as received
+   * @param {number} [opts.toleranceSeconds=300]  reject deliveries older than this
+   * @returns {{ valid: boolean, reason?: string, event?: object }}
+   *          `event` is the parsed payload, present only when valid is true.
+   *
+   * @example
+   * app.post('/hooks', express.raw({ type: 'application/json' }), (req, res) => {
+   *   const { valid, reason, event } = CertySignClient.verifyWebhookSignature({
+   *     secret: process.env.CERTYSIGN_WEBHOOK_SECRET,
+   *     headers: req.headers,
+   *     rawBody: req.body,
+   *   });
+   *   if (!valid) return res.status(401).send(reason);
+   *
+   *   if (alreadyHandled(event.eventId)) return res.sendStatus(200);  // at-least-once
+   *   handle(event);
+   *   res.sendStatus(200);
+   * });
+   */
+  static verifyWebhookSignature({ secret, headers, rawBody, toleranceSeconds = 300 } = {}) {
+    const crypto = require('crypto');
+
+    if (!secret)  return { valid: false, reason: 'secret is required' };
+    if (!headers) return { valid: false, reason: 'headers are required' };
+    if (rawBody === undefined || rawBody === null) {
+      return { valid: false, reason: 'rawBody is required' };
+    }
+
+    // A parsed object means express.json() ran and the original bytes are gone.
+    // Say so plainly, because the signature would simply never match and the
+    // cause is not obvious from a bare "invalid signature".
+    if (typeof rawBody === 'object' && !Buffer.isBuffer(rawBody)) {
+      return {
+        valid: false,
+        reason: 'rawBody looks parsed, not raw. The signature covers the bytes as sent, '
+              + "so use express.raw({ type: 'application/json' }) and pass req.body "
+              + 'unmodified.',
+      };
+    }
+
+    // Headers arrive lower-cased from Node, but a framework may not.
+    const pick = (name) => {
+      const want = name.toLowerCase();
+      if (typeof headers.get === 'function') return headers.get(name) ?? undefined;
+      const hit = Object.keys(headers).find((k) => k.toLowerCase() === want);
+      return hit ? headers[hit] : undefined;
+    };
+
+    const timestamp = pick('X-CertySign-Timestamp');
+    const signature = String(pick('X-CertySign-Signature') || '').replace(/^sha256=/, '');
+
+    if (!timestamp) return { valid: false, reason: 'missing X-CertySign-Timestamp header' };
+    if (!signature) return { valid: false, reason: 'missing X-CertySign-Signature header' };
+
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts)) return { valid: false, reason: 'X-CertySign-Timestamp is not a number' };
+
+    if (toleranceSeconds > 0) {
+      const age = Math.abs(Date.now() / 1000 - ts);
+      if (age > toleranceSeconds) {
+        return { valid: false, reason: `delivery is ${Math.round(age)}s old, outside the ${toleranceSeconds}s tolerance` };
+      }
+    }
+
+    const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), 'utf8');
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body]))
+      .digest('hex');
+
+    // timingSafeEqual throws on a length mismatch, so compare digests of a fixed
+    // length rather than the raw hex.
+    const a = crypto.createHash('sha256').update(signature, 'utf8').digest();
+    const b = crypto.createHash('sha256').update(expected, 'utf8').digest();
+    if (!crypto.timingSafeEqual(a, b)) return { valid: false, reason: 'signature does not match' };
+
+    try {
+      return { valid: true, event: JSON.parse(body.toString('utf8')) };
+    } catch {
+      // Signature is good, so this came from us; the caller still gets the bytes.
+      return { valid: true, event: undefined, reason: 'signature valid but body is not JSON' };
+    }
+  }
 }
 
 /**
@@ -220,6 +363,7 @@ module.exports = {
   // or extend them; the client wires them up as client.signers / client.billing.
   SignerResource,
   BillingResource,
+  WebhookResource,
   // Legacy exports
   SigningResource,
   CertificateResource,

package/src/lib/HttpClient.js

@@ -11,6 +11,14 @@
 'use strict';
 
 const axios = require('axios');
+
+// Reported on every request, so a log can tell which SDK version a caller is on.
+// Read from package.json because a hardcoded literal drifts: this said 1.0.0 for
+// the whole 2.x line. Guarded because a bundler may not ship package.json.
+const SDK_VERSION = (() => {
+  try { return require('../../package.json').version; } catch { return 'unknown'; }
+})();
+const SDK_USER_AGENT = `CertySign-SDK-Node/${SDK_VERSION} Node/${process.version}`;
 const FormData = require('form-data');
 const crypto = require('crypto');
 
@@ -51,7 +59,7 @@ class HttpClient {
       headers: {
         'Content-Type': 'application/json',
         'Accept':       'application/json',
-        'User-Agent':   `CertySign-SDK-Node/1.0.0 Node/${process.version}`
+        'User-Agent':   SDK_USER_AGENT
       }
     });
   }

package/src/lib/IdentityResource.js

@@ -88,8 +88,18 @@ class IdentityResource {
 
     const ctry = String(country).toUpperCase().trim();
     const type = String(idType).toUpperCase().trim();
+    // Warn, do not throw. Which ID types exist for a country is the SERVER's
+    // vocabulary, and it grows. Refusing an unknown type here means that the day the
+    // API starts accepting one, every installed copy of this SDK rejects it before
+    // the request leaves the process — and the only fix is a republish. A warning
+    // still catches a typo during development while leaving the server as the
+    // authority on what it accepts.
     if (SUPPORTED[ctry] && !SUPPORTED[ctry].includes(type)) {
-      throw new Error(`identity.verify: idType '${type}' is not supported for ${ctry} (supported: ${SUPPORTED[ctry].join(', ')})`);
+      console.warn(
+        `[certysign] identity.verify: idType '${type}' was not known for ${ctry} when this ` +
+        `SDK version was published (known: ${SUPPORTED[ctry].join(', ')}). Sending it anyway — ` +
+        `the API decides. Upgrade the SDK to silence this.`
+      );
     }
 
     const body = {

package/src/lib/WebhookResource.js

@@ -0,0 +1,88 @@
+/**
+ * client.webhooks — be told, instead of asking.
+ *
+ * Before these existed the only way to learn that an envelope completed or a
+ * sponsored certificate was issued was to poll, and every poll was billed. Register
+ * an endpoint once and CertySign calls you.
+ *
+ * Deliveries are not charged.
+ */
+class WebhookResource {
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Register an endpoint.
+   *
+   * The signing secret is returned ONCE, in this response. Store it before you do
+   * anything else — there is no way to read it back, only to replace the webhook.
+   *
+   * Requires `webhook:manage`.
+   *
+   * @param {object}   opts
+   * @param {string}   opts.url           https only
+   * @param {string[]} [opts.events]      omit for every event
+   * @param {string}   [opts.description]
+   *
+   * @example
+   * const { data } = await client.webhooks.create({
+   *   url: 'https://api.example.com/certysign/hooks',
+   *   events: ['envelope.completed', 'sponsorship.certificate_issued'],
+   * });
+   * await saveSecret(data.secret);   // shown once
+   */
+  create({ url, events, description } = {}) {
+    if (!url) throw new Error('webhooks.create: url is required');
+    return this._http.post('/sdk/v1/webhooks', {
+      data: { url, ...(events && { events }), ...(description && { description }) },
+    });
+  }
+
+  /** Every webhook on this organisation, plus the list of supported events. */
+  list() {
+    return this._http.get('/sdk/v1/webhooks');
+  }
+
+  /** Stop sending to this endpoint. */
+  remove(webhookId) {
+    if (!webhookId) throw new Error('webhooks.remove: webhookId is required');
+    return this._http.delete(`/sdk/v1/webhooks/${encodeURIComponent(webhookId)}`);
+  }
+
+  /**
+   * Send a real, signed `webhook.test` event.
+   *
+   * Worth doing before anything real depends on it: it is the only way to confirm
+   * your signature check works while a failure still costs nothing.
+   */
+  test(webhookId) {
+    if (!webhookId) throw new Error('webhooks.test: webhookId is required');
+    return this._http.post(`/sdk/v1/webhooks/${encodeURIComponent(webhookId)}/test`, { data: {} });
+  }
+
+  /**
+   * What was sent, when, and what your endpoint said.
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.webhookId]
+   * @param {'pending'|'delivered'|'failed'|'exhausted'} [opts.status]
+   * @param {number} [opts.limit]
+   */
+  deliveries({ webhookId, status, limit } = {}) {
+    const q = new URLSearchParams();
+    if (webhookId) q.set('webhookId', webhookId);
+    if (status) q.set('status', status);
+    if (limit) q.set('limit', String(limit));
+    const qs = q.toString();
+    return this._http.get(`/sdk/v1/webhooks/deliveries${qs ? `?${qs}` : ''}`);
+  }
+
+  /** Send one again, with the same eventId so you can de-duplicate. */
+  redeliver(deliveryId) {
+    if (!deliveryId) throw new Error('webhooks.redeliver: deliveryId is required');
+    return this._http.post(`/sdk/v1/webhooks/deliveries/${encodeURIComponent(deliveryId)}/redeliver`, { data: {} });
+  }
+}
+
+module.exports = { WebhookResource };