Overview
Webhooks allow you to receive real-time notifications when a KYC verification status changes. Gu1 automatically sends HTTP POST requests to your configured webhook endpoint whenever a validation status updates.Why Use Webhooks?
Real-Time Updates
Get instant notifications when verification status changes
Efficient
No need to poll the API repeatedly
Automated Workflows
Automatically update user accounts based on verification results
Better UX
Notify customers immediately after verification
Webhook Events
Gu1 sends webhooks for the following KYC validation events:| Event Type | Description | When Triggered |
|---|---|---|
kyc.validation_created | Validation session created | When you create a new KYC validation |
kyc.validation_in_progress | Customer started verification | Customer begins the verification process |
kyc.validation_approved | Verification approved | Identity successfully verified |
kyc.validation_rejected | Verification rejected | Identity verification failed |
kyc.validation_abandoned | Customer abandoned process | Customer left without completing |
kyc.validation_expired | Validation session expired | Session expired (typically after 7 days) |
Setting Up Webhooks
Step 1: Configure Webhook in Dashboard
Configure your webhook URL in the Gu1 dashboard:-
Navigate to Webhooks Settings
- Log in to your Gu1 dashboard
- Go to Settings → Webhooks
-
Create New Webhook
- Click Add Webhook or Create Webhook
- Enter a descriptive name (e.g., “Production KYC Webhook”)
- Enter your webhook URL (must be HTTPS):
https://yourapp.com/webhooks/kyc
-
Select Environment
- Choose Sandbox for testing
- Choose Production for live events
-
Subscribe to Events
- Select all KYC events or specific ones:
kyc.validation_createdkyc.validation_in_progresskyc.validation_approvedkyc.validation_rejectedkyc.validation_abandonedkyc.validation_expired
- Select all KYC events or specific ones:
-
Save Your Secret
- A webhook secret will be automatically generated
- Copy and save this secret - you’ll need it to verify webhook signatures
- You won’t be able to see it again (but you can regenerate it later)
-
Activate the Webhook
- Toggle the webhook to Enabled
- Click Save
You can create separate webhooks for sandbox and production environments with different URLs.
Step 2: Create a Webhook Endpoint
Create an endpoint in your application to receive webhook POST requests:Step 3: Make Your Endpoint Publicly Accessible
Your webhook endpoint must be:- Publicly accessible via HTTPS
- Able to receive POST requests
- Return a 200 status code quickly (within 30 seconds)
For local development, use tools like ngrok to create a public URL that tunnels to your local server.
Security: Verifying Webhook Signatures
Always verify webhook signatures to ensure requests are coming from Gu1.How Signature Verification Works
- Gu1 generates an HMAC SHA-256 signature of the webhook payload using your secret
- The signature is sent in the
X-Webhook-Signatureheader - Your server recalculates the signature using the same secret
- Compare the signatures - if they match, the webhook is authentic
Signature Verification Examples
HTTP Headers
Every webhook request includes these headers:| Header | Description | Example |
|---|---|---|
Content-Type | Always application/json | application/json |
X-Webhook-Event | Event type | kyc.validation_approved |
X-Webhook-ID | Webhook configuration ID | 550e8400-e29b-41d4-a716-446655440000 |
X-Webhook-Timestamp | ISO 8601 timestamp | 2025-01-15T10:30:00.000Z |
X-Webhook-Signature | HMAC SHA-256 signature | abc123... |
Webhook Payload Structure
All webhooks follow this standard structure:Common Payload Fields
The event type (e.g.,
kyc.validation_approved)ISO 8601 timestamp when the event occurred
Your organization ID
The KYC validation ID in Gu1
The entity (person) ID being verified
Entity information including your
externalId for easy lookupCurrent validation status:
pending, in_progress, approved, rejected, abandoned, expiredEvent-Specific Payloads
kyc.validation_created
Sent when a new KYC validation is created.kyc.validation_in_progress
Sent when a customer starts the verification process.kyc.validation_approved
Sent when verification is successfully completed.verifiedAt: Timestamp when verification was approvedextractedData: Personal information extracted from the documentverifiedFields: Array of fields that were successfully verifiedwarnings: Array of any warnings detected during verificationdecision: Verification results (images/URLs removed for security)
kyc.validation_rejected
Sent when verification fails.kyc.validation_abandoned
Sent when a customer starts but doesn’t complete the verification.kyc.validation_expired
Sent when a validation session expires without completion.Retry Policy
If your webhook endpoint fails to respond with a 2xx status code, Gu1 will automatically retry delivery. Default Retry Policy:- Max Retries: 3 attempts
- Initial Delay: 1000ms (1 second)
- Backoff Multiplier: 2x
- Retry Sequence: 1s → 2s → 4s
- Initial attempt at
T+0s - First retry at
T+1s - Second retry at
T+3s(1s + 2s) - Third retry at
T+7s(1s + 2s + 4s)
- HTTP status codes 200-299 are considered successful
- Any other status code or network error triggers a retry
- Each attempt has a 30-second timeout
- If your endpoint doesn’t respond within 30 seconds, the attempt is marked as failed
Best Practices
Return 200 Quickly
Return 200 Quickly
Always return a 200 status code as quickly as possible to acknowledge receipt. Process the webhook asynchronously if needed.
Verify Signatures
Verify Signatures
Always verify the
X-Webhook-Signature header to ensure the webhook is authentic.Handle Idempotency
Handle Idempotency
You might receive the same webhook multiple times. Use the
validationId to ensure you process each event only once.Use entity.externalId for Lookup
Use entity.externalId for Lookup
The webhook includes
entity.externalId which is the ID you provided when creating the entity. Use this to look up the customer in your database.Store Validation IDs
Store Validation IDs
Store the
validationId from Gu1 in your database. This allows you to query validation details later if needed.Handle Errors Gracefully
Handle Errors Gracefully
If processing fails, log the error but still return 200 to prevent retries. Store failed webhooks for manual review.
Use Environment-Specific Webhooks
Use Environment-Specific Webhooks
Create separate webhook configurations for sandbox and production environments.
- Sandbox: Use for testing with test data
- Production: Use for live customer verifications
Testing Webhooks
Testing in Dashboard
- Go to Settings → Webhooks
- Select your webhook
- Click Test Webhook
- Gu1 will send a test event to your endpoint
- Check the response status and logs
Local Development
Use ngrok to expose your local server:Testing Flow
- Create a sandbox webhook pointing to your development endpoint
- Create a test KYC validation
- Your webhook endpoint receives
kyc.validation_created - Complete the verification (or simulate different outcomes)
- Your webhook endpoint receives status updates
Monitoring and Debugging
Webhook Logs
View webhook delivery history in your dashboard:- Go to Settings → Webhooks
- Select your webhook
- Click View Logs or History
- Timestamp of each delivery attempt
- HTTP status code received
- Response body
- Response time
- Error messages (if any)
- Retry attempts
Webhook Statistics
Each webhook displays:- Total Triggers: Total number of times the webhook was triggered
- Success Count: Successful deliveries
- Failure Count: Failed deliveries
- Last Triggered: Timestamp of last attempt
- Last Success: Timestamp of last successful delivery
- Last Failure: Timestamp of last failed delivery
Troubleshooting
Not Receiving Webhooks
Not Receiving Webhooks
Check these items:
- Webhook URL is publicly accessible via HTTPS
- Firewall allows incoming POST requests from Gu1
- Endpoint returns 200 status code within 30 seconds
- Webhook is configured and enabled in dashboard
- Correct environment selected (sandbox vs production)
- Check server logs for incoming requests
- Verify webhook subscribed to correct event types
Signature Verification Failing
Signature Verification Failing
Common causes:
- Using wrong secret (check dashboard for current secret)
- Verifying signature on parsed JSON instead of raw body
- Secret not properly saved after webhook creation
- Encoding issues (ensure UTF-8)
Receiving Duplicate Webhooks
Receiving Duplicate Webhooks
This is normal behavior. Webhooks may be sent multiple times due to:
- Network issues
- Timeouts
- Retries after failures
validationId and event type.Webhook Endpoint Timing Out
Webhook Endpoint Timing Out
Your endpoint must respond within 30 seconds. If processing takes longer:
Missing extractedData
Missing extractedData
extractedData and verifiedFields are only included in:kyc.validation_approvedkyc.validation_rejected
validation_created or validation_in_progress.Webhook Secret Lost
Webhook Secret Lost
If you lost your webhook secret:
- Go to Settings → Webhooks
- Select your webhook
- Click Regenerate Secret
- Save the new secret in your environment variables
- Update your application with the new secret