@expresscsv/react 0.1.13 → 0.1.15

package/README.md

@@ -283,6 +283,116 @@ function App() {
 }
 ```
 
+### Webhook Payload Structure
+
+Each chunk is delivered as a JSON `POST` (or whichever method you configured) to your endpoint. The request body has this shape:
+
+```typescript
+interface WebhookPayload {
+  /** Imported records for this chunk, matching your schema */
+  records: Record<string, unknown>[];
+  /** 0-based index of the current chunk */
+  chunkIndex: number;
+  /** Total number of chunks in this delivery */
+  totalChunks: number;
+  /** Total number of records across all chunks */
+  totalRecords: number;
+  /** Present only if you passed `metadata` in `WebhookConfig` */
+  metadata?: Record<string, unknown>;
+  /** Delivery context added by ExpressCSV */
+  delivery: {
+    publishableKey: string;
+    environmentName: string;
+    environmentType: string;
+    teamSlug: string;
+    importIdentifier: string;
+    deliveryId: string;
+    timestamp: string; // ISO 8601
+  };
+}
+```
+
+Example payload:
+
+```json
+{
+  "records": [
+    { "name": "Alice Johnson", "email": "alice@example.com" },
+    { "name": "Bob Smith", "email": "bob@example.com" }
+  ],
+  "chunkIndex": 0,
+  "totalChunks": 3,
+  "totalRecords": 2500,
+  "metadata": {
+    "source": "react-app",
+    "userId": "user-123"
+  },
+  "delivery": {
+    "publishableKey": "pk_live_abc123",
+    "environmentName": "Production",
+    "environmentType": "production",
+    "teamSlug": "my-team",
+    "importIdentifier": "user-import",
+    "deliveryId": "del_abc123",
+    "timestamp": "2026-03-02T14:30:00.000Z"
+  }
+}
+```
+
+The request includes a `Content-Type: application/json` header plus any custom `headers` you specified in `WebhookConfig`.
+
+### Handling Webhooks on Your Server
+
+Your endpoint should return a **2xx** status code to acknowledge each chunk. Non-2xx responses trigger the following retry behaviour:
+
+- **5xx** and **429** responses are retried automatically (up to 5 attempts per chunk).
+- **4xx** responses (except 429) are treated as permanent failures and are **not** retried.
+
+Chunks are delivered **serially** — the next chunk is only sent after the previous one succeeds.
+
+Below is a minimal Express.js example:
+
+```typescript
+import express from "express";
+
+const app = express();
+app.use(express.json());
+
+app.post("/webhooks/csv-import", async (req, res) => {
+  const token = req.headers.authorization;
+  if (token !== "Bearer your-api-token") {
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+
+  const { records, chunkIndex, totalChunks, totalRecords, metadata, delivery } =
+    req.body;
+
+  try {
+    // Process the records — e.g. insert into your database
+    await db.insertMany("users", records);
+
+    console.log(
+      `Chunk ${chunkIndex + 1}/${totalChunks} processed ` +
+        `(${records.length} records, delivery ${delivery.deliveryId})`
+    );
+
+    res.status(200).json({ success: true });
+  } catch (error) {
+    // Return 500 so ExpressCSV retries this chunk
+    console.error("Failed to process chunk:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+app.listen(3000);
+```
+
+**Tips:**
+
+- Use `delivery.deliveryId` and `chunkIndex` to **deduplicate** retried chunks (the same chunk may be delivered more than once on retry).
+- Use `chunkIndex` and `totalChunks` to track progress and know when the full import is complete (`chunkIndex === totalChunks - 1` for the last chunk).
+- Store `metadata` alongside imported records if you need to correlate the import with a specific user or action in your app.
+
 ### Combined Local Callback and Webhook
 
 ```tsx