Webhooks

Tuzzle can send HTTP POST notifications to your application when files are uploaded or processed. Configure a webhook URL in your upload config or space settings.

Setting Up Webhooks

Via Upload Config

Include a webhook_url in the config's notifications section:

{
  "config": {
    "notifications": {
      "webhook_url": "https://your-app.com/webhooks/tuzzle"
    }
  }
}

Via Space Settings

Set a webhook URL on the space itself:

curl -X PUT https://api.tzzl.io/api/v1/spaces/SPACE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-app.com/webhooks/tuzzle" }'

Webhook Payload

When a file is uploaded, Tuzzle sends a POST request with the file details:

{
  "event": "file.uploaded",
  "file": {
    "id": "01HQ...",
    "name": "image-01HQ...",
    "original_name": "photo.jpg",
    "mime_type": "image/jpeg",
    "size": 245000,
    "storage_path": "a1b2c3/image-01HQ...",
    "type": "upload",
    "resource_type": "image",
    "space_id": "01HQ..."
  }
}

Webhook Timing

Webhook notifications are dispatched as a post-upload job. They are sent after the file is stored and the database record is created, but may arrive before metadata extraction or blurhash generation complete.

Best Practices

• Use HTTPS endpoints for webhook URLs
• Respond with a 2xx status code quickly (within 5 seconds)
• Process webhook data asynchronously in your application
• Verify the webhook comes from Tuzzle by checking the source IP or implementing a shared secret