xhook-js v0.0.2

Webhook Request Worker

A TypeScript library for reliable processing of webhook requests with automatic batching, error handling, and graceful shutdown capabilities.

Features

• 🚀 Batch processing of webhook requests
• 🔄 Automatic retry mechanism for failed requests
• ⚡ Configurable batch sizes
• 🔒 Request locking mechanism to prevent duplicate processing
• 💪 Built-in error handling and request timeout management
• 🛑 Graceful shutdown support
• 🔍 Detailed logging for monitoring and debugging

Installation

npm install webhook-request-worker
# or
yarn add webhook-request-worker
# or
pnpm add webhook-request-worker

Quick Start

import { WebhookRequestWorker } from "webhook-request-worker";

// Define your webhook request handler
const handleWebhook = async (request) => {
  // Process your webhook request here
  console.log(`Processing webhook: ${request.id}`);
  // Your processing logic...
};

// Create a new worker instance
const worker = new WebhookRequestWorker({
  channelId: "your-channel-id",
  requestHandler: handleWebhook,
  batchSize: 5, // Optional: defaults to 5
});

// Start the worker
await worker.start();

// Handle graceful shutdown (optional)
process.on("SIGTERM", async () => {
  await worker.handleShutdown();
});

API Reference

WebhookRequestWorker

Constructor Options

{
  channelId: string;       // Required: Unique identifier for the webhook channel
  requestHandler: WebhookRequestHandler; // Required: Function to process requests
  batchSize?: number;      // Optional: Number of requests to process in each batch (default: 5)
  workerId?: string;       // Optional: Unique identifier for this worker instance
}

Methods

• start(): Promise<void> - Starts the worker and begins processing requests
• stop(): Promise<void> - Stops the worker and releases any locked requests
• handleShutdown(): Promise<void> - Gracefully shuts down the worker

WebhookRequest Interface

interface WebhookRequest {
  id: string;
  createdAt: string;
  httpUrl: string;
  httpMethod: string;
  httpContentType: string;
  httpHeaders: Record<string, string>;
  httpQueryParams: Record<string, string>;
  data: any;
}

WebhookRequestHandler Type

type WebhookRequestHandler = (request: WebhookRequest) => Promise<void>;

Error Handling

The worker includes built-in error handling for common scenarios:

• Network timeouts (2 seconds for fetching requests)
• Rate limiting (automatic backoff)
• Request processing failures (automatic lock release)
• API errors (with appropriate retry logic)

Configuration

The worker connects to an API endpoint at https://omni.mrfxyz.workers.dev/ and includes the following default configurations:

• Default batch size: 5 requests
• Request fetch timeout: 2 seconds
• Request processing timeout: 5 seconds
• Retry delay: 1-5 seconds (varies based on error type)

Best Practices

1. Error Handling: Always implement proper error handling in your request handler:

   const handler = async (request: WebhookRequest) => {
     try {
       await processWebhook(request);
     } catch (error) {
       console.error("Webhook processing failed:", error);
       throw error; // Worker will handle the error appropriately
     }
   };

2. Graceful Shutdown: Implement shutdown handling in your application:

   const worker = new WebhookRequestWorker(config);
   
   // Handle various shutdown signals
   ["SIGINT", "SIGTERM", "SIGQUIT"].forEach((signal) => {
     process.on(signal, async () => {
       await worker.handleShutdown();
       process.exit(0);
     });
   });

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.