Skip to main content

​
What are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when events occur in your Gu1 organization. Instead of polling the API repeatedly, Gu1 sends automatic POST requests to your configured endpoint whenever something important happens.

​
Why Use Webhooks?

Real-Time Updates

Get instant notifications as events happen

Efficient

No need to poll the API repeatedly

Automated Workflows

Trigger actions automatically based on events

Scalable

Handle high volumes without performance impact

​
How Webhooks Work

  1. Configure a webhook in your Gu1 dashboard
  2. Subscribe to specific event types
  3. Receive HTTP POST requests when events occur
  4. Process events in your application

​
Available Event Types

Gu1 supports webhooks for the following categories:

​
Entity Events

Track changes to persons, companies, and other entities:
  • entity.created - New entity created
  • entity.updated - Entity data updated
  • entity.status_changed - Entity status changed
  • entity.deleted - Entity deleted (coming soon)
Learn more about Entity Events →

​
KYC Events

Monitor identity verification processes:
  • kyc.validation_created - KYC validation started
  • kyc.validation_in_progress - User began verification
  • kyc.validation_approved - Verification approved
  • kyc.validation_rejected - Verification failed
  • kyc.validation_abandoned - User abandoned process
  • kyc.validation_expired - Validation session expired
Learn more about KYC Events →

​
Rule Events

Track compliance and business rule executions:
  • rule.triggered - Rule matched and executed
Learn more about Rule Events →

​
Transaction Events (Coming Soon)

Monitor transaction activity:
  • transaction.created - New transaction recorded
  • transaction.updated - Transaction updated
  • transaction.flagged - Transaction flagged as suspicious

​
Alert Events (Coming Soon)

Track investigations and alerts:
  • alert.created - New alert created
  • alert.resolved - Alert resolved
  • alert.status_changed - Alert status changed

​
Key Features

​
Organization-Level Configuration

Webhooks are configured at the organization level, not per-request. One configuration applies to all matching events in your organization.

​
Environment Support

Create separate webhooks for different environments:
  • Sandbox - For testing and development
  • Production - For live operations

​
Advanced Filtering

Filter which events trigger webhooks:
  • Entity types - Only persons, only companies, etc.
  • Status changes - Only when changing from/to specific statuses
  • Custom filters - Additional criteria based on event data

​
Security

  • HMAC SHA-256 signatures - Verify requests are from Gu1
  • HTTPS required - All webhooks must use secure endpoints
  • Secret rotation - Regenerate secrets anytime

​
Reliability

  • Automatic retries - Failed requests are retried with exponential backoff
  • Configurable retry policy - Customize retry behavior per webhook
  • Delivery logs - Track all delivery attempts and responses

​
Monitoring

  • Execution history - View all webhook deliveries
  • Statistics - Success/failure rates and timing
  • Error tracking - Detailed error messages for debugging

​
Quick Start

Get started with webhooks in 3 steps:
1

Configure Webhook

Go to Settings → Webhooks and create a new webhook with your endpoint URL.Configuration Guide →
2

Subscribe to Events

Select which event types you want to receive (e.g., entity.*, kyc.*).
3

Implement Endpoint

Create an HTTPS endpoint that receives POST requests and verifies signatures.Security Guide →

​
Common Use Cases

Scenario: Automatically activate customer accounts when KYC is approved.Events: kyc.validation_approvedActions:
  • Update customer status in your database
  • Send welcome email
  • Enable account features
  • Notify internal teams
Scenario: Track entity status changes for compliance reporting.Events: entity.status_changed, rule.triggeredActions:
  • Log status changes for audit trail
  • Trigger compliance workflows
  • Send alerts to compliance team
  • Update risk scores
Scenario: Get notified when high-risk transactions are detected.Events: transaction.flagged, alert.createdActions:
  • Notify fraud team immediately
  • Pause related transactions
  • Request additional verification
  • Log for investigation
Scenario: Keep multiple systems synchronized with Gu1 data.Events: All entity and KYC eventsActions:
  • Update CRM with verification status
  • Sync with payment processor
  • Update analytics platform
  • Trigger marketing automation

​
Webhook Structure

All webhooks follow a standard format: 
{
  "event": "entity.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "organizationId": "org-123",
  "payload": {
    // Event-specific data
  }
}
Common fields:
  • event - Event type identifier
  • timestamp - When the event occurred (ISO 8601)
  • organizationId - Your organization ID
  • payload - Event-specific data (varies by event type)

​
Best Practices

Verify Signatures

Always verify HMAC signatures to ensure requests are from Gu1

Respond Quickly

Return 200 status within 30 seconds, process asynchronously

Handle Idempotency

Use event IDs to prevent duplicate processing

Monitor Failures

Track webhook delivery failures and investigate issues

​
Performance & Limits

  • Timeout: 30 seconds per delivery attempt
  • Max Retries: 3 (configurable)
  • Retry Delay: 1s, 2s, 4s (exponential backoff)
  • Payload Size: Up to 1MB per webhook
  • Rate Limit: No enforced limit (best effort delivery)

​
Getting Help

Configuration Guide

Step-by-step setup instructions

Security Guide

Implement signature verification

Event Reference

All available event types

Troubleshooting

Common issues and solutions

​
Next Steps

1

Read Configuration Guide

Learn how to set up webhooks in your dashboardConfiguration Guide →
2

Explore Event Types

See all available events and their payloadsEntity Events →KYC Events →
3

Implement Security

Add signature verification to your endpointSecurity Guide →