NestJS Webhooker

A powerful NestJS module for sending webhooks to other APIs with transactional capabilities. This module allows you to easily integrate webhook functionality into your NestJS applications and provides features such as webhook storage, request and response logging, and transactional sending.

Features

• Webhook Storage: Store all your webhooks, including request and response data, for auditing and analysis purposes.
• Transactional Sending: Ensure reliable delivery of webhooks by implementing transactional sending, with automatic retries and error handling.
• Easy Integration: Seamlessly integrate the module into your existing NestJS applications without hassle.
• Flexible Configuration: Customize the module's behavior and settings to suit your application's specific requirements.
• Request and Response Logging: Log detailed information about each webhook request and its corresponding response for debugging and monitoring purposes.

Installation

$ npm install @mabalashov/nestjs-webhooker

Quick Start

Create the DAO-services to store the webhooks and webhook-requests. They should implement interfaces WebhookRepository and WebhookRequestRepository from the package @mabalashov/nestjs-webhooker The simplest implementation:

import { Injectable } from '@nestjs/common';
import {
  Webhook,
  WebhookRepository as IWebhookRepository,
  WebhookRequestRepository as IWebhookRequestRepository,
  WebhookStatus,
} from '@mabalashov/nestjs-webhooker';

const webhook = {
  method: 'post',
  url: 'https://google.com',
  data: { asd: 'qwe' },
  last_attempt_at: null,
  attempts: 1,
  status: WebhookStatus.RETRYING,
};

@Injectable()
export class WebhookRepository implements IWebhookRepository {
  async *findByStatusesAndLastAttemptAtOlder(
    statuses: WebhookStatus[],
    lastAttemptAtOlder: Date,
  ): AsyncIterableIterator<Webhook> {
    yield { ...webhook }; // get the results from database
  }

  save(webhook: Webhook) {
    console.log('SAVING WEBHOOK', webhook); // store the Webhook in database
  }
}

// ...

@Injectable()
export class WebhookRequestRepository implements IWebhookRequestRepository {
  save(webhookRequest: WebhookRequest, webhook: Webhook) {
    console.log('SAVING WEBHOOK REQUEST', webhookRequest, webhook); // store the WebhookRequest relates to Webhook in the database
  }
}

Import the Webhooker into your root application module:

import { Module } from '@nestjs/common';
import { WebhookSenderModule } from '@mabalashov/nestjs-webhooker';

@Module({
  imports: [
    WebhookerModule.forRootAsync({
      imports: [/* ... */],
      inject: [WebhookRepository, WebhookRequestRepository],
      useFactory: (
        webhookRepository: WebhookRepository,
        webhookRequestRepository: WebhookRequestRepository,
      ) => {
        return {
          webhookRepository,
          webhookRequestRepository,
          // ...
        };
      },
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Once the module is imported, you can use the Webhooker in your application:

import {Injectable} from '@nestjs/common';
import {WebhookerService} from "@mabalashov/nestjs-webhooker";

@Injectable()
export class MyService {
  constructor(private readonly webhooker: WebhookerService) {
  }

  async sendWebhook() {
    // Send a webhook using the Webhooker
    await this.webhooker.send({
      method: 'post',
      url: 'https://google.com',
      data: { qwe: 'asd' },
    });
  }
}

Once you have sent the webhook it will be stored in the database (using the DAO-service you provided) and will be sending http-request until the vendor service will return success response or will reach max limit

Configuration

The Webhooker accepts an optional configuration object during initialization. You can provide the following options:

• executionMiddleware (function): the middleware to wrap the webhook sending method. We use it for implementing semaphore for prevent several requests to be sent simultaneously.
• axiosInstance (AxiosInstance): You can pass the custom axios instance to use instead of basic one.

To customize the module's behavior, update the configuration object passed to Webhooker.forRoot() or Webhooker.forRootAsync() .

Examples

For more detailed examples and usage instructions, please refer to the Examples directory.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

License

This project is licensed under the MIT License.

Thank you for using the NestJS Webhooker! If you have any questions or need further assistance, please open an issue on the GitHub repository.