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

# Webhooks

> Real-time event notifications for your Gumnut integration

# Webhooks

<Note>
  Webhooks are currently under development and not yet available. This documentation outlines the planned implementation.
</Note>

Webhooks will allow you to receive real-time notifications when events occur in your Gumnut account, eliminating the need to poll the API for updates.

## Coming Soon

The webhook system is currently in development. Once launched, it will support:

### Event Types

Planned webhook events include:

**Asset Events**:

* `asset.uploaded` - New asset uploaded
* `asset.processed` - Asset processing completed
* `asset.updated` - Asset metadata updated
* `asset.deleted` - Asset removed

**Album Events**:

* `album.created` - New album created
* `album.updated` - Album modified
* `album.deleted` - Album removed
* `album.asset_added` - Asset added to album
* `album.asset_removed` - Asset removed from album

**People Events**:

* `person.detected` - New person detected
* `person.identified` - Person identified/named
* `person.merged` - Duplicate people merged

**Processing Events**:

* `face.detected` - Faces found in asset
* `embedding.generated` - Search embedding created
* `thumbnail.generated` - Thumbnails ready
* `task.failed` - Background task failed

### Webhook Configuration

You'll be able to configure webhooks through:

* The Gumnut Dashboard
* The REST API
* The SDKs

### Security Features

Planned security features:

* Webhook signature verification
* SSL/TLS endpoint requirement
* Retry logic with exponential backoff
* Event deduplication

### Payload Format

Webhook payloads will follow a consistent structure:

```json theme={null}
{
  "id": "evt_abc123",
  "type": "asset.uploaded",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "asset_id": "asset_xyz789",
    "library_id": "lib_123",
    // Event-specific data
  }
}
```

## Stay Updated

To be notified when webhooks become available:

1. Follow our updates at [www.gumnut.ai/blog](https://www.gumnut.ai/blog)
2. Check this documentation periodically

## Alternative Solutions

While webhooks are in development, you can:

### Polling

Periodically check for updates using the API:

```javascript theme={null}
// Poll for new assets every minute
setInterval(async () => {
  const assets = await client.assets.list({
    created_after: lastCheckTime
  });
  
  if (assets.length > 0) {
    // Process new assets
    handleNewAssets(assets);
    lastCheckTime = new Date();
  }
}, 60000);
```

### Task Monitoring

Track background task completion:

```python theme={null}
# Upload asset and monitor processing
asset = client.assets.create(...)
task_id = asset.processing_task_id

# Poll task status
while True:
    task = client.tasks.get(task_id)
    if task.status == 'completed':
        # Asset processing complete
        break
    elif task.status == 'failed':
        # Handle error
        break
    time.sleep(5)
```

### WebSocket Updates (Planned)

Real-time updates via WebSocket connections are also being considered as an alternative to webhooks for certain use cases.

## Feedback

We're actively developing the webhook system and would love your input:

* What events are most important for your use case?
* What payload information do you need?
* Any specific security requirements?

Share your feedback at [www.gumnut.ai/support](https://www.gumnut.ai/support)

## Next Steps

While waiting for webhooks:

* Explore the [API Overview](/guides/apis/overview) for current capabilities
* Review [Authentication](/guides/authentication/overview) options
* Check out our [SDKs](/guides/sdks/overview) for easier integration
* Use the [MCP Server](/guides/mcp/overview) for AI-assisted development