Express CSV Logo

Webhooks

Use webhook in open() when you want ExpressCSV to deliver validated records directly to your backend.

Basic Webhook Example

importer.open({
  webhook: {
    url: "https://api.example.com/webhooks/csv-import",
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-token",
    },
    metadata: {
      source: "web-app",
      userId: "user-123",
    },
  },
  onComplete: () => {
    console.log("Webhook delivery initiated");
  },
  onError: (error) => {
    console.error("Delivery error", error);
  },
});

Combine Local Processing And Webhooks

importer.open({
  chunkSize: 500,
  onData: async (chunk, next) => {
    await savePreviewRows(chunk.records);
    next();
  },
  webhook: {
    url: "https://api.example.com/webhooks/csv-import",
    headers: {
      Authorization: "Bearer your-api-token",
    },
  },
});

Delivery Behavior

  • Chunks are delivered serially
  • 5xx and 429 responses are retried automatically
  • Most other 4xx responses are not retried
  • Your backend should deduplicate with deliveryId and chunkIndex

Minimal Backend Shape

Your endpoint receives JSON with:

  • records
  • chunkIndex
  • totalChunks
  • totalRecords
  • metadata
  • delivery

Return a 2xx status only after the chunk is safely processed.

If you prefer a hook-based integration, see the React webhook guide.