Webhooks Integration

Receive real-time notifications about signature events with IgniSign webhooks

Introduction to Webhooks

Webhooks allow your application to receive real-time notifications about events occurring in the Ignisign platform. Instead of continuously polling the Ignisign API to check for updates, webhooks push information to your application when events happen, making your integration more efficient and responsive.

Ignisign webhooks can notify your application about various events such as:

• Signature request creation and updates
• Signature completion or failure
• Signer creation and updates
• Signature proof generation
• And many more

This asynchronous notification mechanism ensures you're always up-to-date with the latest events, allowing you to build responsive and event-driven applications.

Webhook Registration

To start receiving webhook notifications, you need to register a webhook endpoint in your Ignisign application environment.

Using the Console

The simplest way to register a webhook is through the Ignisign Console:

1. Navigate to your application's configuration section
2. Select the appropriate environment (development, test, production)
3. Go to the Webhooks section
4. Click "Add Webhook Endpoint"
5. Enter the URL where you want to receive webhook notifications
6. Add an optional description for the webhook
7. Configure which topics you want to receive notifications for

Using the API

You can also register webhooks programmatically using the Ignisign API:

// Initialize the Ignisign client
const ignisign = new IgnisignClient({
appId: 'your-app-id',
appEnv: 'PRODUCTION',
apiKey: 'your-api-key'
});

// Register a new webhook endpoint
const { data } = await ignisign.client.applicationsV4.addWebhookEndpoint(
'your-app-id', 
'PRODUCTION', 
{
  url: 'https://example.com/api/ignisign-webhooks',
  description: 'Webhook for signature events'
}
);

console.log('Webhook registered:', data);
    

The API endpoint for webhook registration is:

POST /v4/applications/:appId/envs/:appEnv/webhooks

With the following request body:

{
  "url": "https://your-endpoint.com/webhook",
  "description": "Optional description of your webhook"
}

Webhook Topics and Events

Ignisign webhooks are organized by topics, with each topic having specific actions. When registering a webhook, you can choose to receive notifications for all topics or disable specific ones.

For detailed information about each webhook topic, payload structure, and examples, refer to the specific webhook documentation:

• Signer Webhooks - Events related to signers
• Signature Request Webhooks - Events related to signature requests
• Signature Session Webhooks - Events related to signature sessions
• Signature Proof Webhooks - Events related to signature proofs
• Signature Images Webhooks - Events related to signature images
• Application Webhooks - Events related to applications
• Document Request Webhooks - Events related to document requests

Available Topics

Webhook topics are defined in the IGNISIGN_WEBHOOK_TOPICS enum:

Topic	Description
APP	Application-related events (settings updates, membership changes, archiving)
SIGNATURE	Signature-related events (completion, failure)
SIGNATURE_REQUEST	Signature request events (initialization, publication, launching)
SIGNER	Signer-related events (creation, claim updates)
SIGNATURE_PROFILE	Signature profile events (creation, archiving)
SIGNATURE_SESSION	Signature session events (session start)
SIGNATURE_PROOF	Signature proof generation events
SIGNATURE_SIGNER_IMAGE	Signature image generation events
SIGNER_ID_PROOFING	ID proofing events (not currently implemented)
SIGNER_AUTH	Authentication events (not currently implemented)

Topic-Specific Actions

Each topic has associated actions:

Application Actions (IGNISIGN_WEBHOOK_ACTION_APPLICATION)

• SETTINGS_UPDATED: Application settings were updated
• MEMBERSHIP_UPDATED: Application membership was updated
• ARCHIVED: Application was archived

Signature Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE)

• SIGNATURE_SUCCESS: Signature was successfully completed
• SIGNATURE_FAILED: Signature failed to complete

Signature Request Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST)

• INIT: Signature request was initialized
• UPDATE: Signature request was updated
• PUBLISH: Signature request was published
• LAUNCHED: Signature request was launched
• CLOSED: Signature request was closed

Signer Actions (IGNISIGN_WEBHOOK_ACTION_SIGNER)

• CREATED: Signer was created
• CLAIM_UPDATED: Signer's claim was updated

Signature Session Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE_SESSION)

• STARTED: Signature session was started
• UPDATED: Signature session was updated

Signature Proof Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROOF)

• GENERATED: Signature proof was generated
• FAILED: Signature proof generation failed

Signature Image Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE_IMAGE)

• GENERATED: Signature image was generated
• FAILED: Signature image generation failed

Signature Profile Actions (IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROFILE)

• CREATED: Signature profile was created
• UPDATED: Signature profile was updated
• ARCHIVED: Signature profile was archived

Message Nature

Each webhook notification also includes a message nature, which indicates the type of notification:

• SUCCESS: Notification about a successful operation
• WARNING: Notification about a warning condition
• ERROR: Notification about an error condition

Webhook Payload Structure

When an event occurs, Ignisign sends a POST request to your webhook URL with a JSON payload containing information about the event. The general structure of a webhook payload is:

{
  "appId": "your-app-id",
  "appEnv": "DEVELOPMENT|TEST|PRODUCTION",
  "topic": "TOPIC_NAME",
  "action": "ACTION_NAME",
  "msgNature": "SUCCESS|WARNING|ERROR",
  "content": { /* Event-specific data */ },
  "verificationToken": "token-for-verification"
}

Example Payloads

Signature Completion Notification

{
  "appId": "app-123456",
  "appEnv": "PRODUCTION",
  "topic": "SIGNATURE",
  "action": "SIGNATURE_SUCCESS",
  "msgNature": "SUCCESS",
  "content": {
    "signatureRequestId": "sr-789012",
    "signerId": "signer-345678",
    "signatureMethod": "DRAW",
    "signatureRequestExternalId": "external-id-123"
  },
  "verificationToken": "verification-token-xyz"
}

Signature Proof Generation Notification

{
  "appId": "app-123456",
  "appEnv": "PRODUCTION",
  "topic": "SIGNATURE_PROOF",
  "action": "GENERATED",
  "msgNature": "SUCCESS",
  "content": {
    "signatureRequestId": "sr-789012",
    "documents": [
      {
        "documentId": "doc-123456",
        "name": "Contract.pdf",
        "contentType": "application/pdf",
        "documentProofToken": "token-123",
        "documentProofUrl": "https://client-sign.ignisign.io/signature-requests/sr-789012/proofs?t=token-123"
      }
    ],
    "signatureRequestExternalId": "external-id-123",
    "signatureProofToken": "token-456",
    "signatureProofUrl": "https://client-sign.ignisign.io/signature-requests/sr-789012/proofs?t=token-456"
  },
  "verificationToken": "verification-token-xyz"
}

Security and Verification

To ensure that webhook notifications are genuinely from Ignisign and haven't been tampered with, each webhook payload includes a verification token.

Verifying Webhook Authenticity

To verify a webhook's authenticity, you can use the provided token:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/api/ignisign-webhooks', async (req, res) => {
try {
  const { appId, appEnv, verificationToken } = req.body;
  
  // Verify the webhook token
  const isValid = await ignisign.tokens.checkConsumeWebhook({
    token: verificationToken,
    appId,
    appEnv
  });
  
  if (isValid) {
    // Process the webhook
    const { topic, action, content } = req.body;
    console.log(`Received webhook: ${topic} - ${action}`);
    
    // Process based on topic and action
    switch(topic) {
      case 'SIGNATURE':
        if (action === 'SIGNATURE_SUCCESS') {
          // Handle successful signature
        }
        break;
      // Handle other topics and actions
    }
    
    res.status(200).send('Webhook received');
  } else {
    console.error('Invalid webhook token');
    res.status(401).send('Invalid token');
  }
} catch (error) {
  console.error('Error processing webhook:', error);
  res.status(500).send('Error processing webhook');
}
});

app.listen(3000, () => {
console.log('Webhook server listening on port 3000');
});
    

The API endpoint for token verification is:

POST /v4/tokens/webhook-verification/checking-consumption

With the following request body:

{
  "token": "verification-token-from-webhook",
  "appId": "your-app-id",
  "appEnv": "DEVELOPMENT|TEST|PRODUCTION"
}

Error Handling and Retries

Ignisign implements a robust error handling and retry mechanism for webhook delivery:

1. When a webhook event is triggered, it's first stored in a database with a status of PENDING
2. The event is then pushed to a queue for asynchronous processing
3. If the delivery to your endpoint fails (non-200 response or timeout), the event status is updated to FAILED
4. Failed events can be manually resent through the Ignisign Console or API

Responding to Webhooks

Your webhook endpoint should:

1. Process the webhook as quickly as possible
2. Return a 200 OK response to acknowledge receipt
3. Perform any time-consuming processing asynchronously

If your endpoint fails to respond with a 200 status code, Ignisign will mark the delivery as failed.

Manually Resending Failed Webhooks

If a webhook delivery fails, you can manually resend it:

1. In the Ignisign Console, navigate to the Webhooks section
2. Select the webhook endpoint
3. Filter events by status "Failed"
4. Click "Resend" on the specific event

You can also resend a webhook programmatically:

POST /v4/webhooks/:webhookId/events/:eventId/resend

SDK Integration Examples

Node.js Integration Example

const express = require('express');
const { IgnisignClient } = require('@ignisign/node');

// Initialize Ignisign client
const ignisign = new IgnisignClient({
appId: 'your-app-id',
appEnv: 'PRODUCTION',
apiKey: 'your-api-key'
});

// Setup webhook handler
const app = express();
app.use(express.json());

app.post('/api/ignisign-webhooks', async (req, res) => {
try {
  const { appId, appEnv, topic, action, msgNature, content, verificationToken } = req.body;
  
  // Verify the webhook token
  const isValid = await ignisign.client.tokensV4.checkConsumeWebhook({
    token: verificationToken,
    appId,
    appEnv
  });
  
  if (!isValid) {
    console.error('Invalid webhook token');
    return res.status(401).send('Invalid token');
  }
  
  // Process based on topic and action
  switch(topic) {
    case 'SIGNATURE':
      if (action === 'SIGNATURE_SUCCESS') {
        const { signatureRequestId, signerId } = content;
        console.log(`Signature completed for request ${signatureRequestId} by signer ${signerId}`);
        
        // Update your database or trigger business logic
        await updateSignatureStatus(signatureRequestId, 'completed');
      }
      break;
      
    case 'SIGNATURE_PROOF':
      if (action === 'GENERATED') {
        const { signatureRequestId, signatureProofUrl } = content;
        console.log(`Signature proof generated for request ${signatureRequestId}`);
        
        // Store the proof URL or download the proof documents
        await storeSignatureProof(signatureRequestId, signatureProofUrl);
      }
      break;
      
    // Handle other topics and actions
  }
  
  // Acknowledge receipt
  res.status(200).send('Webhook processed successfully');
} catch (error) {
  console.error('Error processing webhook:', error);
  res.status(500).send('Error processing webhook');
}
});

app.listen(3000, () => {
console.log('Webhook server listening on port 3000');
});
    

Best Practices

Webhook Implementation Recommendations

1. Respond quickly to webhook requests: Process webhooks asynchronously and respond with a 200 status code immediately to prevent Ignisign from marking the delivery as failed.

2. Implement idempotency: Design your webhook handler to be idempotent, as the same webhook might be delivered multiple times in rare cases.

3. Verify all webhooks: Always verify the webhook token to ensure the request is genuinely from Ignisign.

4. Use HTTPS endpoints: Secure your webhook endpoint with HTTPS to protect the data in transit.

5. Implement proper error handling: Log webhook processing errors and handle them gracefully.

6. Keep track of webhook IDs: Store webhook IDs to prevent duplicate processing.

7. Set up monitoring: Monitor webhook deliveries and set up alerts for failed deliveries.

8. Test your webhook handler: Use the Ignisign Console to manually resend webhooks for testing.

Webhook Flow Diagram

The following diagram illustrates the webhook notification flow:

Webhook Security Verification Flow

Managing Webhooks

Disabling and Enabling Webhook Endpoints

You can temporarily disable a webhook endpoint without deleting it:

1. In the Ignisign Console, navigate to the Webhooks section
2. Select the webhook endpoint
3. Click "Disable Webhook" to pause notifications
4. Click "Enable Webhook" to resume notifications

Disabling Specific Topics

You can also choose to disable specific topics for a webhook endpoint:

1. In the Ignisign Console, navigate to the Webhooks section
2. Select the webhook endpoint
3. Click "Manage Topics"
4. Uncheck the topics you want to disable
5. Click "Save"

Viewing Webhook Event History

The Ignisign Console provides a detailed view of all webhook events:

1. Navigate to the Webhooks section
2. Select the webhook endpoint
3. View all events or filter by status (All, Passed, Failed)
4. Click on an event to see its details, including request and response

This history helps you track webhook deliveries and troubleshoot any issues that may arise.

Conclusion

This guide provided an overview of Ignisign's webhook integration capabilities. For more detailed information about specific webhook events, payloads, and examples, refer to the relevant sections in the Webhooks API documentation.

Remember that webhooks are a powerful way to create real-time integrations with Ignisign's electronic signature platform, allowing your application to immediately respond to signature-related events as they occur.