@edge-markets/connect-node 1.6.1 → 1.7.0

package/README.md

@@ -9,6 +9,8 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 📡 **Full API client** - User, balance, transfers via `forUser()` pattern
 - 🛡️ **Typed errors** - Specific error classes for each scenario
 - 📝 **TypeScript first** - Complete type definitions
+- 🪝 **Webhook signature verification** - Constant-time HMAC-SHA256 with replay protection
+- 🔁 **Webhook reconciliation** - Cursor-based sync for catching missed events
 
 ## Installation
 
@@ -51,10 +53,10 @@ Never expose your client secret to browsers or client-side code.
 
 ```typescript
 interface EdgeConnectServerConfig {
-  clientId: string              // Your OAuth client ID
-  clientSecret: string          // Your OAuth client secret (keep secret!)
+  clientId: string              // Your user-facing OAuth client ID
+  clientSecret: string          // Your user-facing OAuth client secret (keep secret!)
   environment: EdgeEnvironment  // 'production' | 'staging' | 'sandbox'
-  
+
   // Optional
   apiBaseUrl?: string           // Custom API URL (dev only)
   oauthBaseUrl?: string         // Custom OAuth URL (dev only)
@@ -63,6 +65,13 @@ interface EdgeConnectServerConfig {
   onRequest?: (info) => void    // Hook called before each request
   onResponse?: (info) => void   // Hook called after each response
 
+  // Optional: Partner-level credentials for non-user-scoped endpoints.
+  // Required ONLY when calling syncWebhookEvents — the rest of the SDK
+  // works without them. These are a DIFFERENT OAuth client than clientId
+  // (machine-to-machine, not user-facing).
+  partnerClientId?: string
+  partnerClientSecret?: string
+
   // Optional: Message Level Encryption (Connect endpoints only)
   mle?: {
     enabled: boolean
@@ -195,7 +204,10 @@ const session = await client.createVerificationSession(transfer.transferId, {
 // 3. Listen for the postMessage event from the iframe (or poll
 //    getVerificationSessionStatus) to learn when verification completes.
 //    A `transfer.completed` webhook will be delivered to your configured
-//    webhook URL once the transfer settles.
+//    webhook URL once the transfer settles. For browser-crash recovery,
+//    your backend should also reconcile against
+//    GET /v1/partner/webhooks/events/sync using a dashboard
+//    client_credentials token from POST /connect/oauth/token.
 
 // Get transfer status
 const status = await client.getTransfer(transfer.transferId)
@@ -218,6 +230,172 @@ await client.revokeConsent()
 await db.edgeConnections.delete(userId)
 ```
 
+## Webhooks
+
+EDGE Connect delivers webhook events to your server when transfers complete,
+fail, expire, or when a user revokes consent. The SDK provides two helpers:
+**signature verification** for the live HTTP delivery channel, and a
+**reconciliation sync method** for the cron-driven safety net.
+
+### Verify webhook signatures
+
+Every webhook arrives with an `X-Edge-Signature` header in `t=...,v1=...`
+format — HMAC-SHA256 over `${timestamp}.${rawBody}` keyed by your webhook
+secret. Use `verifyWebhookSignature` to check it. The function does
+constant-time comparison and rejects events older than 5 minutes by default
+to prevent replay attacks.
+
+> ⚠️ **The `body` argument MUST be the raw request bytes**, not a parsed
+> object that you re-stringified. `JSON.stringify(req.body)` reorders keys
+> and silently breaks verification with no diagnostic. Always capture the
+> raw body via your framework's raw-body middleware.
+
+```typescript
+import { verifyWebhookSignature, type EdgeWebhookEvent } from '@edge-markets/connect-node'
+import express from 'express'
+
+const app = express()
+
+app.post(
+  '/webhooks/edge',
+  // 👇 Critical: this gives you req.body as a Buffer, not a parsed object
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const ok = verifyWebhookSignature(
+      req.headers['x-edge-signature'] as string,
+      req.body.toString('utf8'),
+      process.env.EDGE_WEBHOOK_SECRET!,
+    )
+    if (!ok) return res.status(401).send('invalid signature')
+
+    const event: EdgeWebhookEvent = JSON.parse(req.body.toString('utf8'))
+    // Process asynchronously and return 200 immediately — see "Best Practices"
+    void processEdgeEvent(event)
+    res.status(200).send('ok')
+  },
+)
+```
+
+#### NestJS
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true })
+
+// edge-webhook.controller.ts
+import { Controller, Post, Req, HttpCode, type RawBodyRequest } from '@nestjs/common'
+import type { Request } from 'express'
+import { verifyWebhookSignature } from '@edge-markets/connect-node'
+
+@Controller('webhooks')
+export class EdgeWebhookController {
+  @Post('edge')
+  @HttpCode(200)
+  handle(@Req() req: RawBodyRequest<Request>) {
+    const ok = verifyWebhookSignature(
+      req.headers['x-edge-signature'] as string,
+      req.rawBody?.toString('utf8') ?? '',
+      process.env.EDGE_WEBHOOK_SECRET!,
+    )
+    if (!ok) throw new UnauthorizedException('invalid signature')
+    // ...
+  }
+}
+```
+
+### Type-safe event handling with `EdgeWebhookEvent`
+
+`EdgeWebhookEvent` is a discriminated union over `event.type`. Switching
+narrows `event.data` automatically — no casts required.
+
+```typescript
+import type { EdgeWebhookEvent } from '@edge-markets/connect-node'
+
+function processEdgeEvent(event: EdgeWebhookEvent) {
+  switch (event.type) {
+    case 'transfer.completed':
+      // event.data is { transferId, status: 'completed', type, amount }
+      creditWallet(event.data.transferId, event.data.amount)
+      break
+    case 'transfer.failed':
+      // event.data.reason is `string | undefined`
+      logFailure(event.data.transferId, event.data.reason ?? 'unknown')
+      break
+    case 'transfer.expired':
+      cancelPending(event.data.transferId)
+      break
+    case 'transfer.processing':
+      // @experimental — reserved for ledger dual-write hand-off
+      break
+    case 'consent.revoked':
+      deactivateLink(event.data.userId, event.data.clientId)
+      break
+    default: {
+      const _exhaustive: never = event
+      return _exhaustive
+    }
+  }
+}
+```
+
+`event.data.amount` is intentionally a `string` (e.g. `'100.00'`), not a
+number, to preserve decimal precision — parse it with a decimal-aware
+library on your side.
+
+### Reconcile missed events with `syncWebhookEvents`
+
+Even with retries and a dead-letter queue, network or partner outages can
+drop webhook events. Run `syncWebhookEvents` from a cron (every ~5 minutes
+is typical) to catch anything your primary receiver missed.
+
+This method requires the partner-level credentials (`partnerClientId` /
+`partnerClientSecret`) on `EdgeConnectServer`. It uses the OAuth
+`client_credentials` grant, caches the partner token internally, and
+handles a 401 by refreshing the token once and retrying.
+
+```typescript
+import { EdgeConnectServer } from '@edge-markets/connect-node'
+
+const edge = new EdgeConnectServer({
+  clientId: process.env.EDGE_CLIENT_ID!,
+  clientSecret: process.env.EDGE_CLIENT_SECRET!,
+  environment: 'staging',
+  partnerClientId: process.env.EDGE_PARTNER_CLIENT_ID!,
+  partnerClientSecret: process.env.EDGE_PARTNER_CLIENT_SECRET!,
+})
+
+async function reconcile() {
+  let cursor = await db.cursors.get('edge') // your stored watermark
+  while (true) {
+    const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+    for (const event of events) {
+      await processEdgeEvent(event) // same idempotent handler as live webhooks
+      cursor = event.id
+    }
+    if (events.length > 0) await db.cursors.set('edge', cursor!)
+    if (!hasMore) break
+  }
+}
+
+setInterval(reconcile, 5 * 60 * 1000)
+```
+
+The server enforces a **30-day lookback**. If your cursor is older than 30
+days, you will receive events from 30 days ago — re-bootstrap from a known
+good state via `getTransfer` if you have been offline for longer.
+
+### Best practices
+
+1. **Verify signatures first** — reject mis-signed events with 401 before
+   doing any work.
+2. **Return 200 immediately** — process events asynchronously. EDGE retries
+   on non-2xx and on responses slower than 10s.
+3. **Be idempotent** — the same event may be delivered more than once
+   (at-least-once delivery). Key your wallet credit / status update on
+   `event.id` or `event.data.transferId`.
+4. **Run reconciliation as a backstop** — webhooks are the fast path,
+   `syncWebhookEvents` is the safety net. They share the same handler.
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as node_https from 'node:https';
-import { EdgeEnvironment, TransferCategory, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens } from '@edge-markets/connect';
-export { Balance, CreateVerificationSessionRequest, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferList, TransferListItem, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
+import { EdgeEnvironment, TransferCategory, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent } from '@edge-markets/connect';
+export { Balance, BaseWebhookEvent, ConsentRevokedEventData, CreateVerificationSessionRequest, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, EdgeWebhookEvent, EdgeWebhookEventType, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferCompletedEventData, TransferExpiredEventData, TransferFailedEventData, TransferList, TransferListItem, TransferProcessingEventData, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 interface RequestInfo {
     method: string;
@@ -42,6 +42,24 @@ interface EdgeConnectServerConfig {
         strictResponseEncryption?: boolean;
     };
     mtls?: MtlsConfig;
+    /**
+     * Partner-level OAuth client ID for the `client_credentials` grant.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     * This is a different OAuth client than {@link clientId} — it authenticates
+     * your backend (not your users) for partner-scoped surfaces like the
+     * webhook reconciliation sync endpoint.
+     *
+     * If omitted, `syncWebhookEvents()` throws on first call but the rest of
+     * the SDK (token exchange, user-scoped API calls) continues to work.
+     */
+    partnerClientId?: string;
+    /**
+     * Partner-level OAuth client secret paired with {@link partnerClientId}.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     */
+    partnerClientSecret?: string;
 }
 interface MtlsConfig {
     enabled: boolean;
@@ -89,6 +107,38 @@ declare class EdgeUserClient {
     getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
+/**
+ * Options for {@link EdgeConnectServer.syncWebhookEvents}.
+ */
+interface SyncWebhookEventsOptions {
+    /**
+     * Cursor token. Pass the `id` of the last event you successfully processed
+     * to receive only newer events. Omit on the first call to start from the
+     * beginning of the 30-day server-side lookback window.
+     */
+    afterEventId?: string;
+    /**
+     * Maximum events per page (1–100). Defaults to 20 server-side.
+     */
+    limit?: number;
+}
+/**
+ * Result of {@link EdgeConnectServer.syncWebhookEvents}. Field names are
+ * normalized to camelCase from the wire format (`has_more` → `hasMore`).
+ */
+interface SyncWebhookEventsResult {
+    /**
+     * Events newer than the supplied cursor, in ascending order. Each event
+     * is the unwrapped {@link EdgeWebhookEvent} payload (the SDK strips the
+     * sync API's outer envelope).
+     */
+    events: EdgeWebhookEvent[];
+    /**
+     * `true` if more events are available beyond this page. Loop while this
+     * is truthy, advancing your cursor to the `id` of the last processed event.
+     */
+    hasMore: boolean;
+}
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
@@ -97,6 +147,7 @@ declare class EdgeConnectServer {
     private readonly retryConfig;
     private readonly httpsAgent;
     private readonly dispatcher;
+    private partnerTokenCache;
     static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
     static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
@@ -116,6 +167,67 @@ declare class EdgeConnectServer {
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
     /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
     _apiRequest<T>(method: string, path: string, accessToken: string, body?: unknown): Promise<T>;
+    /**
+     * Reconcile webhook events from the partner sync endpoint.
+     *
+     * Use this from a scheduled cron (every ~5 minutes is typical) to catch
+     * events your primary webhook receiver missed — partner downtime, retry
+     * exhaustion, dead-letter queue. This is the third reliability layer
+     * ("Leg 3") on top of HTTP delivery + DLQ.
+     *
+     * **Authentication.** This method uses the OAuth `client_credentials`
+     * grant against {@link EdgeConnectServerConfig.partnerClientId} and
+     * {@link EdgeConnectServerConfig.partnerClientSecret}. The token is
+     * cached internally and refreshed automatically.
+     *
+     * **Pagination.** Pass `afterEventId` with the last `id` you processed.
+     * Loop while `hasMore` is true. The server enforces a 30-day lookback;
+     * cursors older than 30 days return events from 30 days ago, not an error.
+     *
+     * @example
+     * ```typescript
+     * let cursor: string | undefined = await loadCursorFromDb()
+     *
+     * while (true) {
+     *   const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+     *   for (const event of events) {
+     *     await processEvent(event)
+     *     cursor = event.id
+     *   }
+     *   if (events.length > 0) await saveCursorToDb(cursor!)
+     *   if (!hasMore) break
+     * }
+     * ```
+     *
+     * @throws {EdgeAuthenticationError} If partner credentials are missing
+     *         or the partner token cannot be obtained / refreshed
+     * @throws {EdgeNetworkError} On network failure
+     * @throws {EdgeApiError} For other non-2xx responses after retries
+     */
+    syncWebhookEvents(options?: SyncWebhookEventsOptions): Promise<SyncWebhookEventsResult>;
+    /**
+     * Builds the sync URL with normalized query parameters.
+     */
+    private buildSyncUrl;
+    /**
+     * Issues a GET to the sync endpoint with the partner Bearer token. Kept
+     * separate from `_apiRequest` because partner tokens have a different
+     * lifecycle (process-wide, client_credentials) than user tokens.
+     */
+    private partnerFetch;
+    /**
+     * Fetches (or returns the cached) partner token via the
+     * `client_credentials` grant. Caches with a 60s safety margin so the
+     * token is renewed *before* the server-side expiry, never racing it.
+     *
+     * Side-effects: writes `this.partnerTokenCache` on success.
+     */
+    private getPartnerToken;
+    /**
+     * @internal Test-only: clears the cached partner token so the next call
+     * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+     */
+    _resetPartnerTokenCache(): void;
     private getRetryDelay;
     private sleep;
     private fetchWithTimeout;
@@ -124,4 +236,68 @@ declare class EdgeConnectServer {
     private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };
+/**
+ * Webhook Signature Verification (SDK-001)
+ *
+ * HMAC-SHA256 verification for EDGE Connect webhook payloads.
+ *
+ * Signature header format: `t={timestamp},v1={hex_hmac}`
+ * Signed message: `{timestamp}.{raw_json_body}`
+ *
+ * The timestamp prefix prevents replay attacks — events older than the
+ * tolerance window (default 5 minutes) are rejected. The HMAC is verified
+ * with constant-time comparison to prevent timing attacks.
+ */
+/**
+ * Options for {@link verifyWebhookSignature}.
+ */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * Maximum age of the signature timestamp, in seconds.
+     *
+     * Signatures older than this are rejected as potential replays.
+     * Defaults to 300 seconds (5 minutes), matching the producer.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verifies an EDGE Connect webhook signature.
+ *
+ * **Always pass the raw request body bytes** — never `JSON.stringify(req.body)`.
+ * Re-stringifying after the framework parses JSON will reorder keys, change
+ * whitespace, and silently break verification with no diagnostic. Capture
+ * the raw body via your framework's raw-body middleware:
+ *
+ * - Express: `express.raw({ type: 'application/json' })`
+ * - Fastify: built-in (use `request.rawBody`)
+ * - NestJS: `{ rawBody: true }` on `NestFactory.create` + `RawBodyRequest<Request>`
+ *
+ * @param header - The `X-Edge-Signature` header value (`t=...,v1=...`)
+ * @param body - The raw request body as a UTF-8 string (NOT a parsed object)
+ * @param secret - The partner's webhook signing secret
+ * @param options - Optional overrides
+ * @returns `true` if the signature is valid and within the tolerance window,
+ *          `false` otherwise. Never throws — malformed input returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@edge-markets/connect-node'
+ *
+ * app.post('/webhooks/edge', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const ok = verifyWebhookSignature(
+ *     req.headers['x-edge-signature'] as string,
+ *     req.body.toString('utf8'),
+ *     process.env.EDGE_WEBHOOK_SECRET!,
+ *   )
+ *
+ *   if (!ok) return res.status(401).send('invalid signature')
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'))
+ *   // ... process event
+ *   res.status(200).send('ok')
+ * })
+ * ```
+ */
+declare function verifyWebhookSignature(header: string, body: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;
+
+export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferOptions, type VerifyWebhookSignatureOptions, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as node_https from 'node:https';
-import { EdgeEnvironment, TransferCategory, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens } from '@edge-markets/connect';
-export { Balance, CreateVerificationSessionRequest, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferList, TransferListItem, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
+import { EdgeEnvironment, TransferCategory, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent } from '@edge-markets/connect';
+export { Balance, BaseWebhookEvent, ConsentRevokedEventData, CreateVerificationSessionRequest, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, EdgeWebhookEvent, EdgeWebhookEventType, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferCompletedEventData, TransferExpiredEventData, TransferFailedEventData, TransferList, TransferListItem, TransferProcessingEventData, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 interface RequestInfo {
     method: string;
@@ -42,6 +42,24 @@ interface EdgeConnectServerConfig {
         strictResponseEncryption?: boolean;
     };
     mtls?: MtlsConfig;
+    /**
+     * Partner-level OAuth client ID for the `client_credentials` grant.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     * This is a different OAuth client than {@link clientId} — it authenticates
+     * your backend (not your users) for partner-scoped surfaces like the
+     * webhook reconciliation sync endpoint.
+     *
+     * If omitted, `syncWebhookEvents()` throws on first call but the rest of
+     * the SDK (token exchange, user-scoped API calls) continues to work.
+     */
+    partnerClientId?: string;
+    /**
+     * Partner-level OAuth client secret paired with {@link partnerClientId}.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     */
+    partnerClientSecret?: string;
 }
 interface MtlsConfig {
     enabled: boolean;
@@ -89,6 +107,38 @@ declare class EdgeUserClient {
     getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
+/**
+ * Options for {@link EdgeConnectServer.syncWebhookEvents}.
+ */
+interface SyncWebhookEventsOptions {
+    /**
+     * Cursor token. Pass the `id` of the last event you successfully processed
+     * to receive only newer events. Omit on the first call to start from the
+     * beginning of the 30-day server-side lookback window.
+     */
+    afterEventId?: string;
+    /**
+     * Maximum events per page (1–100). Defaults to 20 server-side.
+     */
+    limit?: number;
+}
+/**
+ * Result of {@link EdgeConnectServer.syncWebhookEvents}. Field names are
+ * normalized to camelCase from the wire format (`has_more` → `hasMore`).
+ */
+interface SyncWebhookEventsResult {
+    /**
+     * Events newer than the supplied cursor, in ascending order. Each event
+     * is the unwrapped {@link EdgeWebhookEvent} payload (the SDK strips the
+     * sync API's outer envelope).
+     */
+    events: EdgeWebhookEvent[];
+    /**
+     * `true` if more events are available beyond this page. Loop while this
+     * is truthy, advancing your cursor to the `id` of the last processed event.
+     */
+    hasMore: boolean;
+}
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
@@ -97,6 +147,7 @@ declare class EdgeConnectServer {
     private readonly retryConfig;
     private readonly httpsAgent;
     private readonly dispatcher;
+    private partnerTokenCache;
     static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
     static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
@@ -116,6 +167,67 @@ declare class EdgeConnectServer {
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
     /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
     _apiRequest<T>(method: string, path: string, accessToken: string, body?: unknown): Promise<T>;
+    /**
+     * Reconcile webhook events from the partner sync endpoint.
+     *
+     * Use this from a scheduled cron (every ~5 minutes is typical) to catch
+     * events your primary webhook receiver missed — partner downtime, retry
+     * exhaustion, dead-letter queue. This is the third reliability layer
+     * ("Leg 3") on top of HTTP delivery + DLQ.
+     *
+     * **Authentication.** This method uses the OAuth `client_credentials`
+     * grant against {@link EdgeConnectServerConfig.partnerClientId} and
+     * {@link EdgeConnectServerConfig.partnerClientSecret}. The token is
+     * cached internally and refreshed automatically.
+     *
+     * **Pagination.** Pass `afterEventId` with the last `id` you processed.
+     * Loop while `hasMore` is true. The server enforces a 30-day lookback;
+     * cursors older than 30 days return events from 30 days ago, not an error.
+     *
+     * @example
+     * ```typescript
+     * let cursor: string | undefined = await loadCursorFromDb()
+     *
+     * while (true) {
+     *   const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+     *   for (const event of events) {
+     *     await processEvent(event)
+     *     cursor = event.id
+     *   }
+     *   if (events.length > 0) await saveCursorToDb(cursor!)
+     *   if (!hasMore) break
+     * }
+     * ```
+     *
+     * @throws {EdgeAuthenticationError} If partner credentials are missing
+     *         or the partner token cannot be obtained / refreshed
+     * @throws {EdgeNetworkError} On network failure
+     * @throws {EdgeApiError} For other non-2xx responses after retries
+     */
+    syncWebhookEvents(options?: SyncWebhookEventsOptions): Promise<SyncWebhookEventsResult>;
+    /**
+     * Builds the sync URL with normalized query parameters.
+     */
+    private buildSyncUrl;
+    /**
+     * Issues a GET to the sync endpoint with the partner Bearer token. Kept
+     * separate from `_apiRequest` because partner tokens have a different
+     * lifecycle (process-wide, client_credentials) than user tokens.
+     */
+    private partnerFetch;
+    /**
+     * Fetches (or returns the cached) partner token via the
+     * `client_credentials` grant. Caches with a 60s safety margin so the
+     * token is renewed *before* the server-side expiry, never racing it.
+     *
+     * Side-effects: writes `this.partnerTokenCache` on success.
+     */
+    private getPartnerToken;
+    /**
+     * @internal Test-only: clears the cached partner token so the next call
+     * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+     */
+    _resetPartnerTokenCache(): void;
     private getRetryDelay;
     private sleep;
     private fetchWithTimeout;
@@ -124,4 +236,68 @@ declare class EdgeConnectServer {
     private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };
+/**
+ * Webhook Signature Verification (SDK-001)
+ *
+ * HMAC-SHA256 verification for EDGE Connect webhook payloads.
+ *
+ * Signature header format: `t={timestamp},v1={hex_hmac}`
+ * Signed message: `{timestamp}.{raw_json_body}`
+ *
+ * The timestamp prefix prevents replay attacks — events older than the
+ * tolerance window (default 5 minutes) are rejected. The HMAC is verified
+ * with constant-time comparison to prevent timing attacks.
+ */
+/**
+ * Options for {@link verifyWebhookSignature}.
+ */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * Maximum age of the signature timestamp, in seconds.
+     *
+     * Signatures older than this are rejected as potential replays.
+     * Defaults to 300 seconds (5 minutes), matching the producer.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verifies an EDGE Connect webhook signature.
+ *
+ * **Always pass the raw request body bytes** — never `JSON.stringify(req.body)`.
+ * Re-stringifying after the framework parses JSON will reorder keys, change
+ * whitespace, and silently break verification with no diagnostic. Capture
+ * the raw body via your framework's raw-body middleware:
+ *
+ * - Express: `express.raw({ type: 'application/json' })`
+ * - Fastify: built-in (use `request.rawBody`)
+ * - NestJS: `{ rawBody: true }` on `NestFactory.create` + `RawBodyRequest<Request>`
+ *
+ * @param header - The `X-Edge-Signature` header value (`t=...,v1=...`)
+ * @param body - The raw request body as a UTF-8 string (NOT a parsed object)
+ * @param secret - The partner's webhook signing secret
+ * @param options - Optional overrides
+ * @returns `true` if the signature is valid and within the tolerance window,
+ *          `false` otherwise. Never throws — malformed input returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@edge-markets/connect-node'
+ *
+ * app.post('/webhooks/edge', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const ok = verifyWebhookSignature(
+ *     req.headers['x-edge-signature'] as string,
+ *     req.body.toString('utf8'),
+ *     process.env.EDGE_WEBHOOK_SECRET!,
+ *   )
+ *
+ *   if (!ok) return res.status(401).send('invalid signature')
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'))
+ *   // ... process event
+ *   res.status(200).send('ok')
+ * })
+ * ```
+ */
+declare function verifyWebhookSignature(header: string, body: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;
+
+export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferOptions, type VerifyWebhookSignatureOptions, verifyWebhookSignature };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  EDGE_WEBHOOK_EVENT_TYPES: () => import_connect4.EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError: () => import_connect3.EdgeApiError,
   EdgeAuthenticationError: () => import_connect3.EdgeAuthenticationError,
   EdgeConnectServer: () => EdgeConnectServer,
@@ -49,7 +50,8 @@ __export(index_exports, {
   isEdgeError: () => import_connect3.isEdgeError,
   isIdentityVerificationError: () => import_connect3.isIdentityVerificationError,
   isNetworkError: () => import_connect3.isNetworkError,
-  isProductionEnvironment: () => import_connect4.isProductionEnvironment
+  isProductionEnvironment: () => import_connect4.isProductionEnvironment,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -58,6 +60,14 @@ var import_connect2 = require("@edge-markets/connect");
 
 // src/validators.ts
 var import_connect = require("@edge-markets/connect");
+var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validateTransferId(transferId) {
+  if (typeof transferId !== "string" || !UUID_V4_REGEX.test(transferId)) {
+    throw new import_connect.EdgeValidationError("transferId must be a UUID v4", {
+      transferId: ["Must be a valid UUID v4"]
+    });
+  }
+}
 function validateVerifyIdentityOptions(options) {
   const errors = {};
   const firstName = typeof options.firstName === "string" ? options.firstName.trim() : "";
@@ -135,6 +145,7 @@ var EdgeUserClient = class {
     return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
   }
   async getTransfer(transferId) {
+    validateTransferId(transferId);
     return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
   }
   async listTransfers(params) {
@@ -155,6 +166,7 @@ var EdgeUserClient = class {
    * The handoff token is single-use and expires in 120 seconds.
    */
   async createVerificationSession(transferId, options) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "POST",
       `/transfer/${encodeURIComponent(transferId)}/verification-session`,
@@ -167,6 +179,7 @@ var EdgeUserClient = class {
    * Use as an alternative to postMessage events.
    */
   async getVerificationSessionStatus(transferId, sessionId) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "GET",
       `/transfer/${encodeURIComponent(transferId)}/verification-session/${encodeURIComponent(sessionId)}`,
@@ -319,18 +332,8 @@ function environmentRequiresMtls(environment, apiBaseUrl) {
   }
 }
 var EdgeConnectServer = class _EdgeConnectServer {
-  static getInstance(config) {
-    const key = getInstanceKey(config);
-    const existing = instances.get(key);
-    if (existing) return existing;
-    const instance = new _EdgeConnectServer(config);
-    instances.set(key, instance);
-    return instance;
-  }
-  static clearInstances() {
-    instances.clear();
-  }
   constructor(config) {
+    this.partnerTokenCache = null;
     if (!config.clientId) {
       throw new Error("EdgeConnectServer: clientId is required");
     }
@@ -359,6 +362,17 @@ var EdgeConnectServer = class _EdgeConnectServer {
       );
     }
   }
+  static getInstance(config) {
+    const key = getInstanceKey(config);
+    const existing = instances.get(key);
+    if (existing) return existing;
+    const instance = new _EdgeConnectServer(config);
+    instances.set(key, instance);
+    return instance;
+  }
+  static clearInstances() {
+    instances.clear();
+  }
   /**
    * Returns the `node:https.Agent` configured with mTLS client certificates.
    * Use this with axios, got, or other HTTP clients. Returns `undefined` if mTLS is not configured.
@@ -529,6 +543,175 @@ var EdgeConnectServer = class _EdgeConnectServer {
       lastError
     );
   }
+  /**
+   * Reconcile webhook events from the partner sync endpoint.
+   *
+   * Use this from a scheduled cron (every ~5 minutes is typical) to catch
+   * events your primary webhook receiver missed — partner downtime, retry
+   * exhaustion, dead-letter queue. This is the third reliability layer
+   * ("Leg 3") on top of HTTP delivery + DLQ.
+   *
+   * **Authentication.** This method uses the OAuth `client_credentials`
+   * grant against {@link EdgeConnectServerConfig.partnerClientId} and
+   * {@link EdgeConnectServerConfig.partnerClientSecret}. The token is
+   * cached internally and refreshed automatically.
+   *
+   * **Pagination.** Pass `afterEventId` with the last `id` you processed.
+   * Loop while `hasMore` is true. The server enforces a 30-day lookback;
+   * cursors older than 30 days return events from 30 days ago, not an error.
+   *
+   * @example
+   * ```typescript
+   * let cursor: string | undefined = await loadCursorFromDb()
+   *
+   * while (true) {
+   *   const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+   *   for (const event of events) {
+   *     await processEvent(event)
+   *     cursor = event.id
+   *   }
+   *   if (events.length > 0) await saveCursorToDb(cursor!)
+   *   if (!hasMore) break
+   * }
+   * ```
+   *
+   * @throws {EdgeAuthenticationError} If partner credentials are missing
+   *         or the partner token cannot be obtained / refreshed
+   * @throws {EdgeNetworkError} On network failure
+   * @throws {EdgeApiError} For other non-2xx responses after retries
+   */
+  async syncWebhookEvents(options = {}) {
+    if (!this.config.partnerClientId) {
+      throw new import_connect2.EdgeAuthenticationError("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
+    }
+    if (!this.config.partnerClientSecret) {
+      throw new import_connect2.EdgeAuthenticationError("syncWebhookEvents requires `partnerClientSecret` in EdgeConnectServer config");
+    }
+    const url = this.buildSyncUrl(options);
+    let token = await this.getPartnerToken();
+    let response = await this.partnerFetch(url, token);
+    if (response.status === 401) {
+      this.partnerTokenCache = null;
+      token = await this.getPartnerToken();
+      response = await this.partnerFetch(url, token);
+      if (response.status === 401) {
+        const body = await response.json().catch(() => ({}));
+        throw new import_connect2.EdgeAuthenticationError(
+          body.message || "Partner token rejected after refresh \u2014 check partnerClientId/Secret",
+          body
+        );
+      }
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new import_connect2.EdgeApiError(
+        body.error || "sync_failed",
+        body.message || `syncWebhookEvents failed with status ${response.status}`,
+        response.status,
+        body
+      );
+    }
+    const wire = await response.json().catch(() => ({}));
+    const events = (wire.events ?? []).map((entry) => entry.payload).filter((p) => !!p);
+    return {
+      events,
+      hasMore: !!wire.has_more
+    };
+  }
+  /**
+   * Builds the sync URL with normalized query parameters.
+   */
+  buildSyncUrl(options) {
+    const url = new URL(`${this.apiBaseUrl}/partner/webhooks/events/sync`);
+    if (options.afterEventId) {
+      url.searchParams.set("after_event_id", options.afterEventId);
+    }
+    if (options.limit !== void 0) {
+      url.searchParams.set("limit", String(options.limit));
+    }
+    return url.toString();
+  }
+  /**
+   * Issues a GET to the sync endpoint with the partner Bearer token. Kept
+   * separate from `_apiRequest` because partner tokens have a different
+   * lifecycle (process-wide, client_credentials) than user tokens.
+   */
+  async partnerFetch(url, token) {
+    try {
+      return await this.fetchWithTimeout(
+        url,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT
+          }
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new import_connect2.EdgeNetworkError("syncWebhookEvents network failure", error);
+    }
+  }
+  /**
+   * Fetches (or returns the cached) partner token via the
+   * `client_credentials` grant. Caches with a 60s safety margin so the
+   * token is renewed *before* the server-side expiry, never racing it.
+   *
+   * Side-effects: writes `this.partnerTokenCache` on success.
+   */
+  async getPartnerToken() {
+    const cached = this.partnerTokenCache;
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.token;
+    }
+    const tokenUrl = `${this.oauthBaseUrl}/token`;
+    let response;
+    try {
+      response = await this.fetchWithTimeout(
+        tokenUrl,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": USER_AGENT
+          },
+          body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.partnerClientId,
+            client_secret: this.config.partnerClientSecret
+          }).toString()
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new import_connect2.EdgeNetworkError("Partner token request network failure", error);
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new import_connect2.EdgeAuthenticationError(
+        body.message || body.error_description || `Partner token request failed with status ${response.status}`,
+        body
+      );
+    }
+    const data = await response.json().catch(() => ({}));
+    if (!data.access_token || typeof data.expires_in !== "number") {
+      throw new import_connect2.EdgeAuthenticationError("Partner token response missing access_token or expires_in");
+    }
+    this.partnerTokenCache = {
+      token: data.access_token,
+      expiresAt: Date.now() + (data.expires_in - 60) * 1e3
+    };
+    return data.access_token;
+  }
+  /**
+   * @internal Test-only: clears the cached partner token so the next call
+   * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+   */
+  _resetPartnerTokenCache() {
+    this.partnerTokenCache = null;
+  }
   getRetryDelay(attempt) {
     const { backoff, baseDelayMs } = this.retryConfig;
     if (backoff === "exponential") {
@@ -638,11 +821,41 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
 };
 
+// src/webhook-signing.ts
+var import_node_crypto = __toESM(require("crypto"));
+function verifyWebhookSignature(header, body, secret, options = {}) {
+  if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
+    return false;
+  }
+  const requestedTolerance = options.toleranceSeconds;
+  const toleranceSeconds = typeof requestedTolerance === "number" && Number.isFinite(requestedTolerance) && requestedTolerance >= 0 ? requestedTolerance : 300;
+  const parts = header.split(",").map((p) => p.trim());
+  const tPart = parts.find((p) => p.startsWith("t="));
+  const v1Part = parts.find((p) => p.startsWith("v1="));
+  if (!tPart || !v1Part) return false;
+  const timestamp = parseInt(tPart.slice(2), 10);
+  const signature = v1Part.slice(3);
+  if (isNaN(timestamp) || !signature) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+  const signedContent = `${timestamp}.${body}`;
+  const expectedHmac = import_node_crypto.default.createHmac("sha256", secret).update(signedContent).digest("hex");
+  try {
+    const sigBuf = Buffer.from(signature, "hex");
+    const expBuf = Buffer.from(expectedHmac, "hex");
+    if (sigBuf.length !== expBuf.length) return false;
+    return import_node_crypto.default.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var import_connect3 = require("@edge-markets/connect");
 var import_connect4 = require("@edge-markets/connect");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError,
   EdgeAuthenticationError,
   EdgeConnectServer,
@@ -662,5 +875,6 @@ var import_connect4 = require("@edge-markets/connect");
   isEdgeError,
   isIdentityVerificationError,
   isNetworkError,
-  isProductionEnvironment
+  isProductionEnvironment,
+  verifyWebhookSignature
 });

package/dist/index.mjs

@@ -21,6 +21,14 @@ import {
 
 // src/validators.ts
 import { EdgeValidationError } from "@edge-markets/connect";
+var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validateTransferId(transferId) {
+  if (typeof transferId !== "string" || !UUID_V4_REGEX.test(transferId)) {
+    throw new EdgeValidationError("transferId must be a UUID v4", {
+      transferId: ["Must be a valid UUID v4"]
+    });
+  }
+}
 function validateVerifyIdentityOptions(options) {
   const errors = {};
   const firstName = typeof options.firstName === "string" ? options.firstName.trim() : "";
@@ -98,6 +106,7 @@ var EdgeUserClient = class {
     return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
   }
   async getTransfer(transferId) {
+    validateTransferId(transferId);
     return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
   }
   async listTransfers(params) {
@@ -118,6 +127,7 @@ var EdgeUserClient = class {
    * The handoff token is single-use and expires in 120 seconds.
    */
   async createVerificationSession(transferId, options) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "POST",
       `/transfer/${encodeURIComponent(transferId)}/verification-session`,
@@ -130,6 +140,7 @@ var EdgeUserClient = class {
    * Use as an alternative to postMessage events.
    */
   async getVerificationSessionStatus(transferId, sessionId) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "GET",
       `/transfer/${encodeURIComponent(transferId)}/verification-session/${encodeURIComponent(sessionId)}`,
@@ -282,18 +293,8 @@ function environmentRequiresMtls(environment, apiBaseUrl) {
   }
 }
 var EdgeConnectServer = class _EdgeConnectServer {
-  static getInstance(config) {
-    const key = getInstanceKey(config);
-    const existing = instances.get(key);
-    if (existing) return existing;
-    const instance = new _EdgeConnectServer(config);
-    instances.set(key, instance);
-    return instance;
-  }
-  static clearInstances() {
-    instances.clear();
-  }
   constructor(config) {
+    this.partnerTokenCache = null;
     if (!config.clientId) {
       throw new Error("EdgeConnectServer: clientId is required");
     }
@@ -322,6 +323,17 @@ var EdgeConnectServer = class _EdgeConnectServer {
       );
     }
   }
+  static getInstance(config) {
+    const key = getInstanceKey(config);
+    const existing = instances.get(key);
+    if (existing) return existing;
+    const instance = new _EdgeConnectServer(config);
+    instances.set(key, instance);
+    return instance;
+  }
+  static clearInstances() {
+    instances.clear();
+  }
   /**
    * Returns the `node:https.Agent` configured with mTLS client certificates.
    * Use this with axios, got, or other HTTP clients. Returns `undefined` if mTLS is not configured.
@@ -492,6 +504,175 @@ var EdgeConnectServer = class _EdgeConnectServer {
       lastError
     );
   }
+  /**
+   * Reconcile webhook events from the partner sync endpoint.
+   *
+   * Use this from a scheduled cron (every ~5 minutes is typical) to catch
+   * events your primary webhook receiver missed — partner downtime, retry
+   * exhaustion, dead-letter queue. This is the third reliability layer
+   * ("Leg 3") on top of HTTP delivery + DLQ.
+   *
+   * **Authentication.** This method uses the OAuth `client_credentials`
+   * grant against {@link EdgeConnectServerConfig.partnerClientId} and
+   * {@link EdgeConnectServerConfig.partnerClientSecret}. The token is
+   * cached internally and refreshed automatically.
+   *
+   * **Pagination.** Pass `afterEventId` with the last `id` you processed.
+   * Loop while `hasMore` is true. The server enforces a 30-day lookback;
+   * cursors older than 30 days return events from 30 days ago, not an error.
+   *
+   * @example
+   * ```typescript
+   * let cursor: string | undefined = await loadCursorFromDb()
+   *
+   * while (true) {
+   *   const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+   *   for (const event of events) {
+   *     await processEvent(event)
+   *     cursor = event.id
+   *   }
+   *   if (events.length > 0) await saveCursorToDb(cursor!)
+   *   if (!hasMore) break
+   * }
+   * ```
+   *
+   * @throws {EdgeAuthenticationError} If partner credentials are missing
+   *         or the partner token cannot be obtained / refreshed
+   * @throws {EdgeNetworkError} On network failure
+   * @throws {EdgeApiError} For other non-2xx responses after retries
+   */
+  async syncWebhookEvents(options = {}) {
+    if (!this.config.partnerClientId) {
+      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
+    }
+    if (!this.config.partnerClientSecret) {
+      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientSecret` in EdgeConnectServer config");
+    }
+    const url = this.buildSyncUrl(options);
+    let token = await this.getPartnerToken();
+    let response = await this.partnerFetch(url, token);
+    if (response.status === 401) {
+      this.partnerTokenCache = null;
+      token = await this.getPartnerToken();
+      response = await this.partnerFetch(url, token);
+      if (response.status === 401) {
+        const body = await response.json().catch(() => ({}));
+        throw new EdgeAuthenticationError(
+          body.message || "Partner token rejected after refresh \u2014 check partnerClientId/Secret",
+          body
+        );
+      }
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new EdgeApiError(
+        body.error || "sync_failed",
+        body.message || `syncWebhookEvents failed with status ${response.status}`,
+        response.status,
+        body
+      );
+    }
+    const wire = await response.json().catch(() => ({}));
+    const events = (wire.events ?? []).map((entry) => entry.payload).filter((p) => !!p);
+    return {
+      events,
+      hasMore: !!wire.has_more
+    };
+  }
+  /**
+   * Builds the sync URL with normalized query parameters.
+   */
+  buildSyncUrl(options) {
+    const url = new URL(`${this.apiBaseUrl}/partner/webhooks/events/sync`);
+    if (options.afterEventId) {
+      url.searchParams.set("after_event_id", options.afterEventId);
+    }
+    if (options.limit !== void 0) {
+      url.searchParams.set("limit", String(options.limit));
+    }
+    return url.toString();
+  }
+  /**
+   * Issues a GET to the sync endpoint with the partner Bearer token. Kept
+   * separate from `_apiRequest` because partner tokens have a different
+   * lifecycle (process-wide, client_credentials) than user tokens.
+   */
+  async partnerFetch(url, token) {
+    try {
+      return await this.fetchWithTimeout(
+        url,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT
+          }
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new EdgeNetworkError("syncWebhookEvents network failure", error);
+    }
+  }
+  /**
+   * Fetches (or returns the cached) partner token via the
+   * `client_credentials` grant. Caches with a 60s safety margin so the
+   * token is renewed *before* the server-side expiry, never racing it.
+   *
+   * Side-effects: writes `this.partnerTokenCache` on success.
+   */
+  async getPartnerToken() {
+    const cached = this.partnerTokenCache;
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.token;
+    }
+    const tokenUrl = `${this.oauthBaseUrl}/token`;
+    let response;
+    try {
+      response = await this.fetchWithTimeout(
+        tokenUrl,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": USER_AGENT
+          },
+          body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.partnerClientId,
+            client_secret: this.config.partnerClientSecret
+          }).toString()
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new EdgeNetworkError("Partner token request network failure", error);
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new EdgeAuthenticationError(
+        body.message || body.error_description || `Partner token request failed with status ${response.status}`,
+        body
+      );
+    }
+    const data = await response.json().catch(() => ({}));
+    if (!data.access_token || typeof data.expires_in !== "number") {
+      throw new EdgeAuthenticationError("Partner token response missing access_token or expires_in");
+    }
+    this.partnerTokenCache = {
+      token: data.access_token,
+      expiresAt: Date.now() + (data.expires_in - 60) * 1e3
+    };
+    return data.access_token;
+  }
+  /**
+   * @internal Test-only: clears the cached partner token so the next call
+   * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+   */
+  _resetPartnerTokenCache() {
+    this.partnerTokenCache = null;
+  }
   getRetryDelay(attempt) {
     const { backoff, baseDelayMs } = this.retryConfig;
     if (backoff === "exponential") {
@@ -601,6 +782,35 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
 };
 
+// src/webhook-signing.ts
+import crypto from "crypto";
+function verifyWebhookSignature(header, body, secret, options = {}) {
+  if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
+    return false;
+  }
+  const requestedTolerance = options.toleranceSeconds;
+  const toleranceSeconds = typeof requestedTolerance === "number" && Number.isFinite(requestedTolerance) && requestedTolerance >= 0 ? requestedTolerance : 300;
+  const parts = header.split(",").map((p) => p.trim());
+  const tPart = parts.find((p) => p.startsWith("t="));
+  const v1Part = parts.find((p) => p.startsWith("v1="));
+  if (!tPart || !v1Part) return false;
+  const timestamp = parseInt(tPart.slice(2), 10);
+  const signature = v1Part.slice(3);
+  if (isNaN(timestamp) || !signature) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+  const signedContent = `${timestamp}.${body}`;
+  const expectedHmac = crypto.createHmac("sha256", secret).update(signedContent).digest("hex");
+  try {
+    const sigBuf = Buffer.from(signature, "hex");
+    const expBuf = Buffer.from(expectedHmac, "hex");
+    if (sigBuf.length !== expBuf.length) return false;
+    return crypto.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 import {
   EdgeApiError as EdgeApiError2,
@@ -619,8 +829,14 @@ import {
   isIdentityVerificationError,
   isNetworkError
 } from "@edge-markets/connect";
-import { TRANSFER_CATEGORIES, getEnvironmentConfig as getEnvironmentConfig2, isProductionEnvironment } from "@edge-markets/connect";
+import {
+  EDGE_WEBHOOK_EVENT_TYPES,
+  TRANSFER_CATEGORIES,
+  getEnvironmentConfig as getEnvironmentConfig2,
+  isProductionEnvironment
+} from "@edge-markets/connect";
 export {
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError2 as EdgeApiError,
   EdgeAuthenticationError2 as EdgeAuthenticationError,
   EdgeConnectServer,
@@ -640,5 +856,6 @@ export {
   isEdgeError,
   isIdentityVerificationError,
   isNetworkError,
-  isProductionEnvironment
+  isProductionEnvironment,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-node",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Server SDK for EDGE Connect token exchange and API calls",
   "author": "Edge Markets",
   "license": "MIT",
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@edge-markets/connect": "^1.5.1"
+    "@edge-markets/connect": "^1.6.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",