Skip to main content

​
Webhooks

Webhooks are currently under development and not yet available. This documentation outlines the planned implementation.
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: 
{
  "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. Join our waitlist at www.gumnut.ai/waitlist
  2. Follow our updates at www.gumnut.ai/blog
  3. Check this documentation periodically

​
Alternative Solutions

While webhooks are in development, you can:

​
Polling

Periodically check for updates using the API: 
// 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: 
# 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

​
Next Steps

While waiting for webhooks: