Node.js Implementation of Ignisign API SDK

This documentation guides you through the Node.js implementation of the Ignisign API SDK, simplifying the integration of Ignisign API with your backend.

Pre-requisites

Before you begin, ensure you have an API key and defined webhook endpoints.

Installation

Install the library via npm:

npm install @ignisign/sdk

Additionally, consider installing the @ignisign/public package, which includes all types utilized by the library. While it's a transitive dependency of @ignisign/sdk and not mandatory, installing it directly can enhance your development experience, especially for IDE import mechanisms.

npm install @ignisign/public

Integration Example

Find an example of integration in this GitHub repository.

Initiate the IgnisignSdk Class

import { IgnisignSdk } from "@ignisign/sdk"

const ignisignSdkInstance = new IgnisignSdk({
  apiKey: "skv2_your_api_key_here",
  displayWarning: true,
});

await ignisignSdkInstance.init();

Create the key in the IgniSign console, under API Keys. It starts with skv2_. Call init() before any other method.

An object with appId, appEnv and appSecret is still accepted. New keys use apiKey.

Easy API Calls

The IgnisignSdk class exposes all API endpoints as methods for easy access.

• An implementation example is available here,

Example Implementation

async function createNewSigner(
  signatureProfileId, 
  inputs: { [key in IGNISIGN_SIGNER_CREATION_INPUT_REF] ?: string } = {}, 
  externalId: string = null): Promise<IgnisignSigner_CreationResponseDto> {  

  const dto: IgnisignSigner_CreationRequestDto = {
    signatureProfileId,
    ...inputs,
    ...(externalId && {externalId})
  };

  try {
    return await ignisignSdkInstance.createSigner(dto);
  } catch (error) {
    console.error(error.toString());
    throw error;
  }
}

Linking Your Webhook Endpoint to Ignisign SDK

Easily connect your webhook endpoint to the Ignisign SDK:

router.post('/v1/ignisign-webhook', async (req, res, next) => {
  try {
    const result = await IgnisignSdkManagerSignatureService.consumeWebhook(req.body);
    jsonSuccess(res, result);
  } catch (e) {
    next(e);
  }
});

The SDK manages webhook signature verification and calls the appropriate callback method based on the webhook type.

Registering Webhook Callbacks

You can register callbacks for various webhook events, as described in the Webhook Events Documentation.

Example Webhook Callback Registration:

const exampleWebhookCallback = async (
  webhookContext: IgnisignWebhookDto,
  error: IgnisignError = null,
  msgNature?: IGNISIGN_WEBHOOK_MESSAGE_NATURE,
  action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST,
  topic?: IGNISIGN_WEBHOOK_TOPICS  
): Promise<boolean> => {

  console.log("Received webhook", webhookContext, topic, action, msgNature);
  return true;
};

await ignisignSdkInstance.registerWebhookCallback(
  exampleWebhookCallback,
  IGNISIGN_WEBHOOK_TOPICS.SIGNATURE,
  IGNISIGN_WEBHOOK_ACTION_SIGNATURE.FINALIZED
);

Simplified Registration of Common Webhook Callbacks

To streamline the implementation of frequently used webhook callbacks, we've introduced a series of "shortcut" functions. These functions provide an more efficient way to handle common webhook scenarios. Below is a list of these functions:

  registerWebhookCallback_Signature(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Signature>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE
  ): Promise<string>;

  registerWebhookCallback_SignatureSession(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureSession>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_SESSION
  ): Promise<string>;

  registerWebhookCallback_DocumentRequest(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_DocumentRequest>, 
    action?: IGNISIGN_WEBHOOK_ACTION_DOCUMENT_REQUEST
  ): Promise<string>;

  registerWebhookCallback_SignatureRequest(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureRequest>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST
  ): Promise<string>;

  registerWebhookCallback_SignatureProfile(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureProfile>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROFILE
  ): Promise<string>;

  registerWebhookCallback_Signer(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Signer>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNER
  ): Promise<string>;

  registerWebhookCallback_SignatureProof(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureProof>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROOF
  ): Promise<string>;

  registerWebhookCallback_SignatureImageGenerated(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureImage>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_IMAGE
  ): Promise<string>;

  registerWebhookCallback_Application(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Application>, 
    action?: IGNISIGN_WEBHOOK_ACTION_APPLICATION
  ): Promise<string>;

Example of Implementation

Here is an example to illustrate how these shortcut functions can be implemented:

const webhookHandler_SignatureRequest = async (
    content: IgnisignWebhookDto_SignatureRequest,
    error: IgnisignError = null,
    msgNature?: IGNISIGN_WEBHOOK_MESSAGE_NATURE,
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST,
    topic?: IGNISIGN_WEBHOOK_TOPICS
  ): Promise<any> => {

    if (msgNature === IGNISIGN_WEBHOOK_MESSAGE_NATURE.ERROR) {
      console.error("handleSignatureRequestWebhookSigners ERROR : ", error);
      return;
    }

    console.log("handleSignatureRequestWebhookSigners : ", content);
};

await ignisignSdkInstance.registerWebhookCallback_SignatureRequest(
    webhookHandler_SignatureRequest,  
    IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST.LAUNCHED
);