Skip to main content

Setup Webhook Forwarding URL

Overview​

The Setup Webhook API registers a forwarding webhook URL for a specific application. This enables routing of identity verification events from providers (like Sumsub) to application-specific endpoints, allowing for tenant-specific callbacks and downstream system integrations.

Authentication​

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Endpoint​

POST /api/applications/{applicationId}/setupwebhook

Path Parameters​

  • applicationId (required): The unique identifier of the application for which to configure the webhook

Request Body​

Interface Definitions​

interface SetupWebhookRequest {
   webhookUrl: string;
}

interface SetupWebhookResponse {
   statusCode: number;
   data: {
      message: string;
      applicationId: string;
      webhookUrl: string;
   };
}

Request Example​

{
   "webhookUrl": "https://your-domain.com/api/kyc/webhook"
}

Response Structure​

Success Response​

{
   "statusCode": 200,
   "data": {
      "message": "Webhook setup successfully",
      "applicationId": "68ef2012876e76eb50626f29",
      "webhookUrl": "https://your-domain.com/api/kyc/webhook"
   }
}

Error Response​

{
   "statusCode": 400,
   "message": "Invalid webhook URL",
   "errors": [
      {
         "field": "webhookUrl",
         "message": "URL must use HTTPS protocol"
      }
   ]
}

Field Validation Requirements​

Webhook URL Validation​

  • Protocol: Must use HTTPS for security
  • Format: Must be a valid URL format
  • Accessibility: Should be publicly accessible for webhook delivery
  • Response: Endpoint should respond to POST requests
  • Authentication: Consider implementing webhook signature verification

Required Fields​

  • webhookUrl: Valid HTTPS URL string (required)

Usage Guidelines​

Webhook Configuration​

The webhook URL will receive POST requests containing:

  • KYC verification status updates
  • Document processing results
  • Identity verification completion events
  • Error notifications from the verification process

Event Forwarding Flow​

  1. Provider Event: Identity provider (Sumsub) sends event to primary webhook
  2. Event Processing: System processes and validates the event
  3. Application Routing: Event is forwarded to application-specific webhook URL
  4. Delivery Confirmation: System tracks delivery status and retries if needed

Integration Patterns​

  • Tenant-Specific Routing: Configure different endpoints for different tenants
  • Event Filtering: Filter events based on application configuration
  • Retry Logic: Implement proper retry mechanisms for failed deliveries
  • Signature Verification: Validate webhook authenticity using signatures

Webhook Payload Structure​

Event Types​

The webhook will receive various event types:

  • kyc.status.updated: Verification status changes
  • kyc.document.processed: Document processing completion
  • kyc.verification.completed: Full verification workflow completion
  • kyc.error: Processing errors or failures

Example Webhook Payload​

{
   "eventType": "kyc.status.updated",
   "applicationId": "68ef2012876e76eb50626f29",
   "applicantId": "68edee456a03b3a57aff8040",
   "timestamp": "2024-01-15T10:30:00.000Z",
   "data": {
      "status": "approved",
      "previousStatus": "pending",
      "documents": [
         "https://storage.googleapis.com/.../document1.jpeg",
         "https://storage.googleapis.com/.../document2.jpeg"
      ],
      "reviewResult": {
         "score": 0.95,
         "decision": "approved",
         "reasons": []
      }
   },
   "metadata": {
      "provider": "sumsub",
      "providerEventId": "evt_123456",
      "retryCount": 0
   }
}

Error Handling​

Common Error Scenarios​

  • 400 Bad Request: Invalid webhook URL format or protocol
  • 401 Unauthorized: Authentication failure
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Application not found
  • 409 Conflict: Webhook URL already configured
  • 500 Internal Server Error: Temporary service issues

Webhook Delivery Errors​

The system handles webhook delivery failures with:

  • Retry Logic: Exponential backoff with maximum retry attempts
  • Dead Letter Queue: Failed events are stored for manual review
  • Status Monitoring: Track delivery success rates and failure patterns
  • Alerting: Notifications for persistent delivery failures

Security Considerations​

HTTPS Requirement​

  • All webhook URLs must use HTTPS for secure transmission
  • SSL certificate validation is performed during setup
  • Insecure connections are rejected to protect sensitive data

Signature Verification​

Consider implementing webhook signature verification:

  • Generate and validate HMAC signatures
  • Include timestamp validation to prevent replay attacks
  • Use secure secret management for signing keys

Data Protection​

  • Webhook payloads contain sensitive personal information
  • Implement proper access controls on receiving endpoints
  • Log webhook events for audit and compliance purposes
  • Follow data retention policies for webhook data

Usage Examples​

Basic Setup​

curl -X POST \
  'https://api.speedydd.com/api/applications/68ef2012876e76eb50626f29/setupwebhook' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "webhookUrl": "https://your-domain.com/api/kyc/webhook"
  }'

Webhook Endpoint Implementation​

// Example webhook receiver
app.post('/api/kyc/webhook', (req, res) => {
   const { eventType, applicationId, data } = req.body;

   // Verify webhook signature (recommended)
   if (!verifySignature(req)) {
      return res.status(401).send('Unauthorized');
   }

   // Process the event
   switch (eventType) {
      case 'kyc.status.updated':
         handleStatusUpdate(applicationId, data);
         break;
      case 'kyc.verification.completed':
         handleVerificationCompletion(applicationId, data);
         break;
      default:
         console.log('Unknown event type:', eventType);
   }

   // Acknowledge receipt
   res.status(200).send('OK');
});

Best Practices​

Endpoint Design​

  1. Idempotency: Handle duplicate webhook deliveries gracefully
  2. Fast Response: Return HTTP 200 quickly to acknowledge receipt
  3. Async Processing: Process webhook data asynchronously
  4. Error Handling: Return appropriate HTTP status codes

Monitoring and Maintenance​

  1. Health Checks: Monitor webhook endpoint availability
  2. Performance Metrics: Track processing times and success rates
  3. Log Analysis: Monitor for patterns in webhook failures
  4. Regular Testing: Validate webhook functionality periodically
Integration Tip

Set up webhook monitoring and alerting to ensure you don't miss important verification events that could impact your user experience.

Important

Always use HTTPS URLs for webhooks and implement proper signature verification to ensure security and authenticity of webhook events.