@neo-edi/sdk 1.0.20 → 1.0.21

package/README.md

@@ -267,6 +267,94 @@ const data = await client.graphql.query<{ edi852Headers: Edi852Header[] }>(`
 `, { filter: { vendorPartnerId: 'VENDOR-001' } });
 ```
 
+## Webhooks
+
+Register endpoints that receive HMAC-signed HTTP callbacks when events happen for a
+trading partner — e.g. `document.ingested` when a delivery is ingested — so you don't
+have to poll.
+
+```typescript
+// Create (subscribe) an endpoint.
+// The returned signingSecret is shown ONCE — store it now.
+const endpoint = await client.webhooks.create({
+  partnerId: 'PARTNER-001',
+  url: 'https://your-app.com/hooks/neo-edi',
+  description: 'Production receiver',
+  eventTypes: ['document.ingested']   // omit to subscribe to all events
+});
+console.log(endpoint.signingSecret);  // whsec_... — persist this securely
+
+// List endpoints for a partner
+const endpoints = await client.webhooks.list('PARTNER-001');
+
+// Get one endpoint
+const one = await client.webhooks.get(endpoint.id);
+
+// Update — change the URL, events, or pause delivery with isActive: false
+await client.webhooks.update(endpoint.id, {
+  url: 'https://your-app.com/hooks/neo-edi/v2',
+  isActive: false
+});
+
+// Delete (unsubscribe)
+await client.webhooks.delete(endpoint.id);
+
+// Inspect recent delivery attempts (audit / debugging)
+const deliveries = await client.webhooks.listDeliveries(endpoint.id, { limit: 20 });
+for (const d of deliveries) {
+  console.log(d.status, d.responseStatus, d.attemptCount);
+}
+```
+
+### Receiving & verifying deliveries
+
+Each delivery is an HTTP `POST` to your URL with a JSON envelope
+(`{ id, type, partnerId, createdAt, data }`) and these headers:
+
+| Header | Example | Purpose |
+|--------|---------|---------|
+| `X-Webhook-Timestamp` | `1717416000` | Unix seconds; part of the signed content |
+| `X-Webhook-Signature` | `t=1717416000,v1=9f86d08...` | `v1` is the HMAC-SHA256 hex digest |
+
+Verify by recomputing `HMAC_SHA256(signingSecret, "{timestamp}.{rawBody}")` over the
+**raw** body (before JSON parsing) and comparing it to the `v1=` value. Example with
+Express:
+
+```typescript
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+
+// Capture the raw body — the signature is computed over the exact bytes sent.
+app.post(
+  '/hooks/neo-edi',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const sig = req.header('X-Webhook-Signature') ?? '';
+    const parts = Object.fromEntries(sig.split(',').map((kv) => kv.split('=')));
+    const rawBody = req.body.toString('utf8');
+
+    const expected = crypto
+      .createHmac('sha256', process.env.WEBHOOK_SECRET!)
+      .update(`${parts.t}.${rawBody}`)
+      .digest('hex');
+
+    const valid =
+      parts.v1?.length === expected.length &&
+      crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
+
+    if (!valid) return res.status(401).send('bad signature');
+
+    const event = JSON.parse(rawBody);
+    // Dedupe on event.id — it is stable across retries.
+    // ... handle event.data ...
+
+    res.sendStatus(200); // any 2xx acknowledges; otherwise it's retried (up to 3x)
+  }
+);
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.js

@@ -63,7 +63,7 @@ var NeoEdiValidationError = class extends NeoEdiError {
 // package.json
 var package_default = {
   name: "@neo-edi/sdk",
-  version: "1.0.20",
+  version: "1.0.21",
   description: "TypeScript SDK for the Neo-EDI platform",
   main: "./dist/index.js",
   module: "./dist/index.mjs",

package/dist/index.mjs

@@ -32,7 +32,7 @@ var NeoEdiValidationError = class extends NeoEdiError {
 // package.json
 var package_default = {
   name: "@neo-edi/sdk",
-  version: "1.0.20",
+  version: "1.0.21",
   description: "TypeScript SDK for the Neo-EDI platform",
   main: "./dist/index.js",
   module: "./dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo-edi/sdk",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "TypeScript SDK for the Neo-EDI platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@neo-edi/types": "1.0.20"
+    "@neo-edi/types": "1.0.21"
   },
   "devDependencies": {
     "@types/node": "^20",
@@ -24,7 +24,7 @@
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "@neo-edi/types": "1.0.20"
+    "@neo-edi/types": "1.0.21"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",