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

# Webhook Configuration

> Step-by-step guide to configure webhooks in the Gu1 dashboard, including endpoint setup, event subscriptions, secret rotation, and retries.

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

You do **not** need to provide a webhook secret. Gu1 **automatically generates** a secret when you create a webhook. The dashboard **shows the secret once** right after you create (or regenerate) the webhook—copy it there; it is not shown again in the webhook list. **Your webhooks will receive events even if you do not verify the signature**; verifying the signature (using the secret and the `X-Webhook-Signature` header) is optional but recommended so your endpoint can confirm that the request came from Gu1. The payload shown in **Webhook Monitor** is for debugging only—you must verify using the **raw HTTP body** at receive time; see [Webhook Security](/en/webhooks/security#intermittent-signature-failures).

<Note>
  For local development, use tools like [ngrok](https://ngrok.com/) to create a public URL that tunnels to your local server.
</Note>

## Step-by-Step Configuration

### Step 1: Navigate to Webhooks Settings

1. Log in to your Gu1 dashboard at [app.gu1.ai](https://app.gu1.ai)
2. Go to **Settings** → **Webhooks**
3. Click **Add Webhook** or **Create Webhook**

### Step 2: Basic Information

<Steps>
  <Step title="Name your webhook">
    Enter a descriptive name to identify this webhook

    **Examples**:

    * "Production KYC Webhook"
    * "Sandbox Entity Events"
    * "Compliance Monitoring"
  </Step>

  <Step title="Add description (optional)">
    Add notes about what this webhook is used for

    **Example**: "Sends KYC approval events to our CRM system"
  </Step>

  <Step title="Enter webhook URL">
    Provide the HTTPS endpoint URL that will receive POST requests

    **Requirements**:

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

    **Example**: `https://api.yourapp.com/webhooks/gu1`
  </Step>
</Steps>

### Step 3: Select Environment

Choose which environment this webhook applies to:

<Tabs>
  <Tab title="Sandbox">
    **Use for**:

    * Development and testing
    * Staging environments
    * QA processes

    **Receives**:

    * Events from sandbox API calls
    * Test validations and transactions
  </Tab>

  <Tab title="Production">
    **Use for**:

    * Live production systems
    * Real customer data
    * Critical workflows

    **Receives**:

    * Events from production API calls
    * Real customer verifications
  </Tab>
</Tabs>

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

### Step 4: Subscribe to Events

Select which event types trigger this webhook:

#### Option A: Subscribe to All Events in a Category

* `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)

#### Option B: Subscribe to Specific Events

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`

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

### Step 5: Configure Filters (Optional)

Add filters to receive only relevant events:

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="Custom Filters">
  Add advanced JSON-based filters for complex scenarios:

  ```json theme={null}
  {
    "entityTypes": ["person"],
    "statusChanges": {
      "to": "blocked"
    },
    "entityTypeFilters": {
      "person": {
        "isClient": true
      }
    }
  }
  ```

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

### Step 6: Configure Retry Policy (Optional)

Customize how Gu1 handles failed webhook deliveries:

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

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

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

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

```json theme={null}
{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}
```

<Warning>
  Avoid sending sensitive secrets in custom headers. Use signature verification instead for authentication.
</Warning>

### Step 8: Copy the Generated Secret

You don't need to provide a secret when creating the webhook. After you save it, Gu1 automatically generates a secret and **the dashboard shows it once** in the creation success step. Copy it there—it will not be shown again in the webhook list (you can regenerate a new secret later in the webhook settings if needed).

<Steps>
  <Step title="Copy the secret">
    **IMPORTANT**: Copy and save this secret immediately. You won't be able to see it again in the list.

    The secret looks like: `whsec_abc123def456...`
  </Step>

  <Step title="Store securely">
    Save the secret in your environment variables or secrets manager:

    ```bash theme={null}
    # .env file
    GU1_WEBHOOK_SECRET=whsec_abc123def456...
    ```
  </Step>

  <Step title="Use for verification (optional)">
    Use this secret to verify webhook signatures in your endpoint (header `X-Webhook-Signature`). **Verification is optional**: your webhook will receive events even if you don't verify; verifying is recommended for security.

    [Learn about signature verification →](/en/webhooks/security)
  </Step>
</Steps>

<Warning>
  Never commit webhook secrets to version control. Always use environment variables or a secrets manager.
</Warning>

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

<Steps>
  <Step title="Send test event">
    Click **Test Webhook** in the dashboard

    Gu1 sends a test payload:

    ```json theme={null}
    {
      "event": "webhook.test",
      "timestamp": "2025-01-15T10:30:00Z",
      "webhookId": "webhook-uuid",
      "data": {
        "message": "This is a test webhook from Gu1"
      }
    }
    ```
  </Step>

  <Step title="Verify receipt">
    Check your endpoint logs to confirm:

    * ✅ Request received
    * ✅ Signature verified (if implemented)
    * ✅ 200 status returned
  </Step>

  <Step title="Review logs">
    In the Gu1 dashboard, view the test delivery:

    * HTTP status code
    * Response time
    * Response body
    * Any errors
  </Step>
</Steps>

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

1. Click **Regenerate Secret**
2. Copy the new secret immediately
3. Update your application with new secret
4. Old secret stops working immediately

<Warning>
  Regenerating the secret invalidates the old one. Update your application before regenerating to avoid downtime.
</Warning>

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

1. Click **Delete** on the webhook
2. Confirm deletion
3. Webhook is removed permanently
4. Logs are retained for 90 days

<Warning>
  Deletion cannot be undone. Consider disabling instead if you might need it again.
</Warning>

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

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    Name webhooks clearly to identify their purpose:

    ✅ Good: "Production KYC → CRM Integration"

    ❌ Bad: "Webhook 1"
  </Accordion>

  <Accordion title="Separate Environments">
    Create different webhooks for sandbox and production:

    * Different URLs (staging vs production)
    * Test in sandbox first
    * Never mix environments
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Monitor Regularly">
    Check webhook health weekly:

    * Review success rates
    * Investigate failures
    * Check response times
    * Update filters as needed
  </Accordion>

  <Accordion title="Document Your Webhooks">
    Keep internal documentation:

    * Which webhook handles what
    * What actions it triggers
    * Who owns the integration
    * Troubleshooting steps
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Duplicate Events">
    This is normal behavior due to retries. Always implement idempotency using event IDs.

    [Learn about handling duplicates →](/en/webhooks/security)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Implement Your Endpoint" icon="code" href="/en/webhooks/security">
    Create an endpoint with signature verification
  </Card>

  <Card title="Explore Event Types" icon="list" href="/en/webhooks/events/entity-events">
    See all available events and payloads
  </Card>

  <Card title="Review Security Guide" icon="shield-check" href="/en/webhooks/security">
    Learn about HMAC signature verification
  </Card>

  <Card title="View Example Code" icon="file-code" href="/en/webhooks/events/kyc-events">
    See complete implementation examples
  </Card>
</CardGroup>