> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Real-time HTTP notifications for events in your Gu1 organization — configure endpoints, subscribe to event types, and integrate downstream systems.

## 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?

<CardGroup cols={2}>
  <Card title="Real-Time Updates" icon="bolt">
    Get instant notifications as events happen
  </Card>

  <Card title="Efficient" icon="gauge-high">
    No need to poll the API repeatedly
  </Card>

  <Card title="Automated Workflows" icon="robot">
    Trigger actions automatically based on events
  </Card>

  <Card title="Scalable" icon="chart-line">
    Handle high volumes without performance impact
  </Card>
</CardGroup>

## How Webhooks Work

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant Gu1 as Gu1 Platform
    participant Endpoint as Your Webhook Endpoint

    App->>Gu1: Configure webhook URL
    Note over Gu1: Event occurs<br/>(entity created, KYC approved, etc.)
    Gu1->>Endpoint: POST /webhooks<br/>with event data
    Endpoint->>Gu1: 200 OK
    Note over Endpoint: Process event<br/>asynchronously
```

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 →](/en/webhooks/events/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 →](/en/webhooks/events/kyc-events)

### Rule Events

Track compliance and business rule executions:

* `rule.triggered` - Rule matched and executed

[Learn more about Rule Events →](/en/webhooks/events/rule-events)

### Risk Analysis Events

Get notified when a risk matrix execution completes:

* `risk_analysis_entity_executed` - Risk matrix run on person or company
* `risk_analysis_transaction_executed` - Risk matrix run on transaction

[Learn more about Risk Analysis Events →](/en/webhooks/events/risk-analysis-events)

### Security & IAM Events

Monitor authentication, members, roles, and security settings for SIEM integrations:

* `security.auth.login_succeeded` / `security.auth.logout` / `security.auth.login_failed`
* `security.member.*` - Member invited, created, removed, activated, profile, password (admin), teams, channels, and environment access (production/sandbox)
* `security.role.*` - Role CRUD, assign, revoke
* `security.rbac.granular_toggled` - Granular RBAC enabled/disabled
* `security.settings.updated` - Sandbox and other audited security settings

[Learn more about Security Events →](/en/webhooks/events/security-events)

### Transaction Events (Coming Soon)

Monitor transaction activity:

* `transaction.created` - New transaction recorded
* `transaction.updated` - Transaction updated (full snapshot; includes status changes)
* `transaction.status_changed` - Status transition only (compact payload when status changes)
* `transaction.flagged` - Transaction flagged as suspicious

[Learn more about Transaction Events →](/en/webhooks/events/transaction-events)

### 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:

<Steps>
  <Step title="Configure Webhook">
    Go to **Settings → Webhooks** and create a new webhook with your endpoint URL.

    [Configuration Guide →](/en/webhooks/configuration)
  </Step>

  <Step title="Subscribe to Events">
    Select which event types you want to receive (e.g., `entity.*`, `kyc.*`).
  </Step>

  <Step title="Implement Endpoint">
    Create an HTTPS endpoint that receives POST requests and verifies signatures.

    [Security Guide →](/en/webhooks/security)
  </Step>
</Steps>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Automated Customer Onboarding">
    **Scenario**: Automatically activate customer accounts when KYC is approved.

    **Events**: `kyc.validation_approved`

    **Actions**:

    * Update customer status in your database
    * Send welcome email
    * Enable account features
    * Notify internal teams
  </Accordion>

  <Accordion title="Real-Time Compliance Monitoring">
    **Scenario**: Track entity status changes for compliance reporting.

    **Events**: `entity.status_changed`, `rule.triggered`

    **Actions**:

    * Log status changes for audit trail
    * Trigger compliance workflows
    * Send alerts to compliance team
    * Update risk scores
  </Accordion>

  <Accordion title="Transaction Risk Alerts">
    **Scenario**: Get notified when high-risk transactions are detected.

    **Events**: `transaction.flagged`, `alert.created`

    **Actions**:

    * Notify fraud team immediately
    * Pause related transactions
    * Request additional verification
    * Log for investigation
  </Accordion>

  <Accordion title="Multi-System Integration">
    **Scenario**: Keep multiple systems synchronized with Gu1 data.

    **Events**: All entity and KYC events

    **Actions**:

    * Update CRM with verification status
    * Sync with payment processor
    * Update analytics platform
    * Trigger marketing automation
  </Accordion>
</AccordionGroup>

## Webhook Structure

All webhooks follow a standard format:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Verify Signatures" icon="shield-check">
    Always verify HMAC signatures to ensure requests are from Gu1
  </Card>

  <Card title="Respond Quickly" icon="gauge-max">
    Return 200 status within 30 seconds, process asynchronously
  </Card>

  <Card title="Handle Idempotency" icon="repeat">
    Use event IDs to prevent duplicate processing
  </Card>

  <Card title="Monitor Failures" icon="chart-line">
    Track webhook delivery failures and investigate issues
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/en/webhooks/configuration">
    Step-by-step setup instructions
  </Card>

  <Card title="Security Guide" icon="lock" href="/en/webhooks/security">
    Implement signature verification
  </Card>

  <Card title="Event Reference" icon="list" href="/en/webhooks/events/entity-events">
    All available event types
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/en/webhooks/security">
    Common issues and solutions
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Read Configuration Guide">
    Learn how to set up webhooks in your dashboard

    [Configuration Guide →](/en/webhooks/configuration)
  </Step>

  <Step title="Explore Event Types">
    See all available events and their payloads

    [Entity Events →](/en/webhooks/events/entity-events)

    [KYC Events →](/en/webhooks/events/kyc-events)
  </Step>

  <Step title="Implement Security">
    Add signature verification to your endpoint

    [Security Guide →](/en/webhooks/security)
  </Step>
</Steps>