Webhooks & API

Webhooks allow Smart KYC to send real-time notifications to your systems when events occur, enabling seamless integration with your existing infrastructure.

What are Webhooks?

Webhooks are HTTP callbacks that send data to a URL you specify when specific events happen in Smart KYC. This allows your systems to:

• Receive instant notifications
• Automatically process submissions
• Sync data in real-time
• Trigger workflows in your systems

Setting Up Webhooks

Prerequisites

Before setting up webhooks, you need:

• A publicly accessible URL endpoint
• An endpoint that accepts POST requests
• SSL certificate (HTTPS required)
• API credentials (API Key and Secret)

Get Your API Credentials

1. Navigate to Webhooks in the sidebar
2. Go to the Webhooks & API tab
3. Find your API Key and API Secret
4. Click Show to reveal the secret (only shown once)
5. Copy and securely store your credentials

Important: Keep your API Secret secure. It cannot be retrieved after initial creation. If lost, you’ll need to rotate your API key.

Create a Webhook

1. Navigate to Webhooks → Webhooks & API
2. Click Create Webhook or Add Webhook
3. Fill in the webhook form:
   • Name: Descriptive name for your webhook
   • URL: Your endpoint URL (must be HTTPS)
   • Status: Active or Inactive
   • Headers (optional): Custom headers to include
4. Click Save

Configure Webhook Headers

Add custom headers for authentication or identification:

1. Click Add Header
2. Enter:
   • Header Name: e.g., “Authorization”, “X-API-Key”
   • Header Value: The header value
3. Click Add

Common use cases:

• API authentication
• Request identification
• Custom routing

Webhook Events

Webhooks are triggered by the following events:

Submission Events

• submission.created: New submission started
• submission.completed: Submission completed
• submission.approved: Submission approved
• submission.rejected: Submission rejected
• submission.updated: Submission updated

Invitation Events

• invitation.sent: Invitation sent to customer
• invitation.expired: Invitation expired
• invitation.cancelled: Invitation cancelled

AML Events

• aml.screening.completed: AML screening completed
• aml.match.found: AML match detected
• aml.match.dismissed: AML match dismissed

Webhook Payload

Standard Payload Structure

{
  "event": "submission.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "submissionId": "sub_123456",
    "invitationId": "inv_123456",
    "customerEmail": "customer@example.com",
    "workflowId": "wf_123456",
    "status": "completed",
    "submittedAt": "2024-01-15T10:30:00Z"
  },
  "tenantId": "tenant_123456"
}

Event-Specific Payloads

Submission Completed

{
  "event": "submission.completed",
  "data": {
    "submissionId": "sub_123456",
    "invitationId": "inv_123456",
    "customerEmail": "customer@example.com",
    "workflowId": "wf_123456",
    "workflowName": "Basic KYC",
    "status": "completed",
    "submittedAt": "2024-01-15T10:30:00Z",
    "responses": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com"
    }
  }
}

AML Match Found

{
  "event": "aml.match.found",
  "data": {
    "submissionId": "sub_123456",
    "matchType": "sanctions",
    "matchScore": 0.95,
    "matchedName": "John Doe",
    "sourceList": "OFAC",
    "riskLevel": "high"
  }
}

Webhook Security

Signature Verification

All webhook requests include a signature header for verification:

1. X-SmartKYC-Signature: HMAC-SHA256 signature
2. Verify the signature using your API Secret
3. Compare with calculated signature

Signature Verification Example

const crypto = require("crypto");
 
function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret);
  const calculatedSignature = hmac.update(payload).digest("hex");
  return signature === calculatedSignature;
}

Best Practices

1. Always verify signatures: Never trust unsigned requests
2. Use HTTPS: Webhooks require HTTPS endpoints
3. Validate payloads: Check payload structure and data
4. Handle errors: Return appropriate HTTP status codes
5. Idempotency: Handle duplicate webhook deliveries

Testing Webhooks

Test Webhook

1. Navigate to your webhook
2. Click Test Webhook
3. Select an event type
4. Click Send Test
5. Check your endpoint logs

Webhook Logs

View webhook delivery logs:

1. Navigate to Webhooks → Logs tab
2. View delivery history:
   • Status: Success, Error, Pending
   • Event: Event type
   • Response Code: HTTP status code
   • Timestamp: When sent
   • Response: Server response

Debugging Failed Webhooks

Common issues and solutions:

401 Unauthorized

• Check API credentials
• Verify signature calculation
• Check authentication headers

404 Not Found

• Verify webhook URL is correct
• Check endpoint is accessible
• Ensure HTTPS is used

500 Server Error

• Check server logs
• Verify payload handling
• Check for timeout issues

Timeout

• Increase timeout on your server
• Optimize endpoint processing
• Consider async processing

Managing Webhooks

Edit Webhook

1. Find your webhook in the list
2. Click Edit
3. Modify settings
4. Click Save

Activate/Deactivate

Toggle webhook status:

• Active: Webhooks are sent
• Inactive: Webhooks are paused

Delete Webhook

1. Find your webhook
2. Click Delete
3. Confirm deletion

Note: Deleted webhooks cannot be recovered.

API Endpoints

REST API

Smart KYC also provides REST API endpoints for:

• Retrieving submissions
• Creating invitations
• Updating submissions
• Querying data

See the Integration section for API authentication and endpoint documentation.

API Authentication

Use your API credentials:

• API Key: Included in header or query parameter
• API Secret: Used for signature verification

Rate Limits

API requests are rate-limited:

• Standard: 100 requests per minute
• Burst: Up to 200 requests per minute
• Contact support for higher limits

Best Practices

1. Handle Duplicates

• Webhooks may be delivered multiple times
• Use idempotency keys
• Check if event already processed

2. Process Asynchronously

• Don’t block webhook processing
• Queue events for background processing
• Return 200 OK quickly

3. Log Everything

• Log all webhook deliveries
• Log processing results
• Keep audit trail

4. Monitor Health

• Monitor webhook success rates
• Set up alerts for failures
• Review logs regularly

5. Secure Your Endpoint

• Use HTTPS only
• Verify signatures
• Validate payloads
• Rate limit requests

Related Topics

• KYC Verifications - Understand submission events
• AML Screening - Learn about AML events
• API Integration - Full API documentation