Webhook Configuration

Overview

This guide walks you through configuring webhooks in your Gu1 dashboard. Webhooks are configured at the organization level and apply to all events matching your filters.

Prerequisites

Before configuring webhooks, you need:

✅ An active Gu1 account with admin permissions
✅ A publicly accessible HTTPS endpoint to receive webhooks
✅ (Optional) A webhook secret for signature verification

For local development, use tools like ngrok to create a public URL that tunnels to your local server.

Step-by-Step Configuration

Step 1: Navigate to Webhooks Settings

Log in to your Gu1 dashboard at app.gu1.ai
Go to Settings → Webhooks
Click Add Webhook or Create Webhook

Step 2: Basic Information

Name your webhook

Enter a descriptive name to identify this webhookExamples:

“Production KYC Webhook”
“Sandbox Entity Events”
“Compliance Monitoring”

Add description (optional)

Add notes about what this webhook is used forExample: “Sends KYC approval events to our CRM system”

Enter webhook URL

Provide the HTTPS endpoint URL that will receive POST requestsRequirements:

Must use HTTPS (not HTTP)
Must be publicly accessible
Should return 200 status within 30 seconds

Example: https://api.yourapp.com/webhooks/gu1

Step 3: Select Environment

Choose which environment this webhook applies to:

Sandbox
Production

Use for:

Development and testing
Staging environments
QA processes

Receives:

Events from sandbox API calls
Test validations and transactions

You can create separate webhooks for sandbox and production with different URLs. This allows safe testing without affecting production systems.

Select which event types trigger this webhook:

entity.* - All entity events
kyc.* - All KYC validation events
rule.* - All rule events
transaction.* - All transaction events (coming soon)
alert.* - All alert events (coming soon)

Select individual events: Entity Events:

☐ entity.created
☐ entity.updated
☐ entity.status_changed
☐ entity.deleted (coming soon)

KYC Events:

☐ kyc.validation_created
☐ kyc.validation_in_progress
☐ kyc.validation_approved
☐ kyc.validation_rejected
☐ kyc.validation_abandoned
☐ kyc.validation_expired

Rule Events:

☐ rule.triggered

Start with specific events you need, then expand as you build more integrations. You can always update subscriptions later.

Step 5: Configure Filters (Optional)

Add filters to receive only relevant events:

Filter by Entity Type

Only trigger webhook for specific entity types:Options:

Person
Company
Device
Payment Method

Example: Only receive events for person entities, ignore companies

Filter by Status Changes

Only trigger when status changes match specific criteria:From Status: Only trigger when changing FROM this status

under_review
active
blocked
pending

To Status: Only trigger when changing TO this status

active
blocked
archived

Example: Only trigger when entities are changed TO blocked status

Filter by Client Flag

Filter events based on the entity’s isClient flag:Options:

Only clients (isClient: true)
Only non-clients (isClient: false)
All entities (no filter)

Example: Only receive events for entities marked as clients

Custom Filters

Add advanced JSON-based filters for complex scenarios:

{
  "entityTypes": ["person"],
  "statusChanges": {
    "to": "blocked"
  },
  "entityTypeFilters": {
    "person": {
      "isClient": true
    }
  }
}

This example only triggers for person entities that are clients when changed to blocked status.

Step 6: Configure Retry Policy (Optional)

Customize how Gu1 handles failed webhook deliveries:

{
  "maxRetries": 3,
  "retryDelayMs": 1000,
  "backoffMultiplier": 2
}

Parameters:

maxRetries - Maximum retry attempts (default: 3)
retryDelayMs - Initial delay before first retry (default: 1000ms)
backoffMultiplier - Multiplier for exponential backoff (default: 2)

Example timeline with defaults:

Initial attempt at T+0s
First retry at T+1s (1000ms)
Second retry at T+3s (1000ms × 2)
Third retry at T+7s (1000ms × 2 × 2)

The default retry policy works well for most use cases. Only customize if you have specific requirements.

Step 7: Add Custom Headers (Optional)

Add custom HTTP headers to webhook requests: Common use cases:

Authorization tokens: Authorization: Bearer token123
API keys: X-API-Key: your-api-key
Custom identifiers: X-Webhook-Source: gu1

Format:

{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}

Avoid sending sensitive secrets in custom headers. Use signature verification instead for authentication.

Step 8: Save Webhook Secret

After creating the webhook, Gu1 automatically generates a secret:

Copy the secret

IMPORTANT: Copy and save this secret immediately. You won’t be able to see it again.The secret looks like: whsec_abc123def456...

Store securely

Save the secret in your environment variables or secrets manager:

# .env file
GU1_WEBHOOK_SECRET=whsec_abc123def456...

Use for verification

Use this secret to verify webhook signatures in your endpoint.Learn about signature verification →

Never commit webhook secrets to version control. Always use environment variables or a secrets manager.

Step 9: Enable Webhook

Toggle the webhook to Enabled status:

✅ Enabled - Webhook actively receives events
⏸️ Disabled - Webhook paused, no events sent

You can disable/enable webhooks anytime without losing configuration.

Step 10: Test Your Webhook

Before going live, test your webhook:

Send test event

Click Test Webhook in the dashboardGu1 sends a test payload:

{
  "event": "webhook.test",
  "timestamp": "2025-01-15T10:30:00Z",
  "webhookId": "webhook-uuid",
  "data": {
    "message": "This is a test webhook from Gu1"
  }
}

Verify receipt

Check your endpoint logs to confirm:

✅ Request received
✅ Signature verified (if implemented)
✅ 200 status returned

Review logs

In the Gu1 dashboard, view the test delivery:

HTTP status code
Response time
Response body
Any errors

Managing Webhooks

View Webhook List

Go to Settings → Webhooks to see all configured webhooks: Information displayed:

Name and description
URL endpoint
Environment (sandbox/production)
Status (enabled/disabled)
Event subscriptions
Statistics (success/failure counts)
Last triggered timestamp

Edit Webhook

Click on a webhook to edit:

✏️ Update name, description, or URL
🔔 Change event subscriptions
🎯 Modify filters
⚙️ Adjust retry policy
🔄 Add/remove custom headers

Changes take effect immediately.

View Webhook Logs

Click View Logs or History to see delivery attempts: Log details:

Timestamp of delivery
Event type
HTTP status code
Response time
Response body
Retry attempt number
Error messages (if failed)

Use cases:

Debug delivery failures
Monitor performance
Investigate duplicate events
Verify event data

Regenerate Secret

If your webhook secret is compromised:

Click Regenerate Secret
Copy the new secret immediately
Update your application with new secret
Old secret stops working immediately

Regenerating the secret invalidates the old one. Update your application before regenerating to avoid downtime.

Disable/Enable Webhook

Temporarily pause a webhook without deleting it:

Click the toggle to Disable
No events will be sent while disabled
All configuration is preserved
Re-enable anytime to resume

Use cases:

Maintenance on your endpoint
Debugging issues
Temporarily stopping event flow

Delete Webhook

Permanently remove a webhook:

Click Delete on the webhook
Confirm deletion
Webhook is removed permanently
Logs are retained for 90 days

Deletion cannot be undone. Consider disabling instead if you might need it again.

Monitoring & Statistics

Each webhook displays key metrics:

Success Rate

Total Triggers: Total delivery attempts
Success Count: Successful deliveries (2xx responses)
Failure Count: Failed deliveries
Success Rate: Percentage of successful deliveries

Timestamps

Last Triggered: Most recent delivery attempt
Last Success: Most recent successful delivery
Last Failure: Most recent failed delivery

Performance

Average Response Time: Average time for your endpoint to respond
P95 Response Time: 95th percentile response time

Use these metrics to:

Identify problematic webhooks
Monitor endpoint health
Optimize webhook processing
Detect delivery issues

Best Practices

Use Descriptive Names

Name webhooks clearly to identify their purpose:✅ Good: “Production KYC → CRM Integration”❌ Bad: “Webhook 1”

Separate Environments

Create different webhooks for sandbox and production:

Different URLs (staging vs production)
Test in sandbox first
Never mix environments

Start with Specific Events

Begin with events you need, expand later:✅ Start: Subscribe to kyc.validation_approved✅ Later: Add kyc.validation_rejected, entity.status_changed

Use Filters Wisely

Add filters to reduce noise:

Filter by entity type if you only care about persons
Filter by status changes for specific transitions
Use custom filters for complex scenarios

Monitor Regularly

Check webhook health weekly:

Review success rates
Investigate failures
Check response times
Update filters as needed

Document Your Webhooks

Keep internal documentation:

Which webhook handles what
What actions it triggers
Who owns the integration
Troubleshooting steps

Troubleshooting

Webhook Not Receiving Events

Checklist:

✅ Webhook is enabled
✅ Correct environment selected
✅ Subscribed to correct event types
✅ Filters not too restrictive
✅ URL is correct and accessible
✅ Endpoint returns 200 status

Check webhook logs for delivery attempts and errors.

All Deliveries Failing

Common causes:

Endpoint is down or unreachable
Firewall blocking Gu1 requests
Endpoint timing out (>30s)
Endpoint returning non-2xx status
SSL certificate issues

Check your server logs and webhook delivery logs in Gu1.

Receiving Too Many Events

Solutions:

Add filters to narrow scope
Unsubscribe from unused event types
Use entity type filters
Add status change filters

Review which events you actually need.

Duplicate Events

This is normal behavior due to retries. Always implement idempotency using event IDs.Learn about handling duplicates →

Next Steps

Implement Your Endpoint

Create an endpoint with signature verification

Explore Event Types

See all available events and payloads

Review Security Guide

Learn about HMAC signature verification

View Example Code

See complete implementation examples

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Prerequisites

​Step-by-Step Configuration

​Step 1: Navigate to Webhooks Settings

​Step 2: Basic Information

​Step 3: Select Environment

​Step 4: Subscribe to Events

​Option A: Subscribe to All Events in a Category

​Option B: Subscribe to Specific Events

​Step 5: Configure Filters (Optional)

​Step 6: Configure Retry Policy (Optional)

​Step 7: Add Custom Headers (Optional)

​Step 8: Save Webhook Secret

​Step 9: Enable Webhook

​Step 10: Test Your Webhook

​Managing Webhooks

​View Webhook List

​Edit Webhook

​View Webhook Logs

​Regenerate Secret

​Disable/Enable Webhook

​Delete Webhook

​Monitoring & Statistics

​Success Rate

​Timestamps

​Performance

​Best Practices

​Troubleshooting

​Next Steps

Implement Your Endpoint

Explore Event Types

Review Security Guide

View Example Code

Overview

Prerequisites

Step-by-Step Configuration

Step 1: Navigate to Webhooks Settings

Step 2: Basic Information

Step 3: Select Environment

Step 4: Subscribe to Events

Option A: Subscribe to All Events in a Category

Option B: Subscribe to Specific Events

Step 5: Configure Filters (Optional)

Step 6: Configure Retry Policy (Optional)

Step 7: Add Custom Headers (Optional)

Step 8: Save Webhook Secret

Step 9: Enable Webhook

Step 10: Test Your Webhook

Managing Webhooks

View Webhook List

Edit Webhook

View Webhook Logs

Regenerate Secret

Disable/Enable Webhook

Delete Webhook

Monitoring & Statistics

Success Rate

Timestamps

Performance

Best Practices

Troubleshooting

Next Steps