Webhole KYC JAAK
Estimated configuration time: 45-60 minutes
What's a Webhole?
A web hook works as an "automessenger" that JAAK send to your system after complete a check KYCenabling real-time processing rather than manual polling of results.
Benefits:
- Automatic performance
- Real-time processing capacity
- Immediate notifications
- Reduced system load compared with polling
Setup Steps
Step 1: Access to Adjustments
Dashboard → Adjustments → My Company → Edit
Step 2: Configure details of the Webhold
| Field | Purpose | Example |
|---|---|---|
| URL | Destination for verification results | https://tu-servidor.com/webhook/kyc |
| Auth Key | Security credit for validation | 16 + character string |
Requirements:
- URLs should use HTTPS protocol
- Just endpoints publicly accessible
- Auth Key minimum 16 characters
- Avoid predictable credentials
Step 3: Implement Endpoint
HTTP specifications:
POST /webhook-endpoint
Content-Type: application/json
Authorization: Bearer [AUTH-KEY]
User-Agent: JAAK-Webhook/1.0
Answer requirements: Your endpoint should respond with HTTP 200 OK in less than 30 seconds.
Retirement policy:
- Initial attempt + 3 maximum reattempts
- Intervales: 1 minute, 5 minutes, 15 minutes
Step 4: Data architecture
The payload of the web hook includes:
- Event: Session completion notification
- Timestamp: Format ISO 8601
- Session ID: Unique identifier
- Verification Status: APPROVED / REJECTED / pENDING / ERROR
- Trust Score: 0-100
- User Data: Name, document number, date of birth, nationality
- Validation Results: document authenticity, facial coincidence, liveness detection
- Methadata: IP address, geolocalisation, device information
Step 5: Tests and Monitoring
Test checklist:
- Webhold URL set up in JAAK
- Auth Key set up with JAAK
- Operating endpoint with HTTPS
- Logging enabled for diagnosis
Verification process:
- Creating Session KYC Test
- Complete check flow
- Monitoring server login
- Validate status at Dashboard JAAK
Interpretation of States
| State | Meaning | Action |
|---|---|---|
| Approved | Successful verification | To activate account |
| REJECTED | Failed verification | Request Reattempt / Additional Documents |
| PENDING | Required manual review | Notify compliance equipment |
| ERROR | Technical failure | Allow Reattempt from User |
Examples of Code
Python (Flask)
Implementation with authentication check, JSON parseus and status-based logic.
Node.js (Express)
Middleware Express, bug management and state routing.
PHP
Native implementation with file_get_contents() for raw input processing.
Problem solving
| Problem | Resolution |
|---|---|
| No webhooks received | Check URL in configuration and confirm server accessibility |
| Authentication challenges | Validar Auth Key; check Leader's format |
| Timeouts | Optimize endpoint response time and move heavy processing to bottom jobs |
| JSON errors | Implement robust bug management and validate field existence |
Best Practices
- Implement idempower management for dual delivery
- Storing web hook signatures for audit traces
- Using background jobs for operations that take time
- Monitoring malfunctions with alert systems
- Documentate Mapping Business Logic for different states