Webhooks

The external upload webhook lets you register assets in Clarento from CI/CD pipelines, design tools, or migration scripts. The asset binary must already be hosted on an accessible CDN — the webhook registers only the metadata.

Endpoint

POST https://<your-webtrigger-url>

The webhook has its own webtrigger URL, separate from the Assets API.

Authentication

Pass your webhook secret in the request body:

{
  "secret": "YOUR_WEBHOOK_SECRET"
}

The secret is configured as a Forge environment variable (WEBHOOK_SECRET). If no secret is configured, all requests are rejected (the webhook requires authentication).

Request Body

{
  "name": "campaign-banner-2026.png",
  "cdnUrl": "https://assets.example.com/campaign-banner-2026.png",
  "thumbnailUrl": "https://assets.example.com/thumbs/campaign-banner-2026.png",
  "mimeType": "image/png",
  "sizeBytes": 524288,
  "tags": ["campaign", "banner", "2026"],
  "campaignId": "summer-2026",
  "uploadedBy": "ci-pipeline",
  "secret": "YOUR_WEBHOOK_SECRET"
}

Required Fields

Field	Type	Description
name	string	Asset filename
cdnUrl	string	Public URL where the file is hosted
mimeType	string	MIME type (e.g., image/png, application/pdf)
sizeBytes	number	File size in bytes
secret	string	Webhook authentication secret

Optional Fields

Field	Type	Description
thumbnailUrl	string	Thumbnail URL (defaults to cdnUrl)
tags	string[]	Tags for organizing the asset
campaignId	string	Campaign identifier
uploadedBy	string	Who uploaded (defaults to external-webhook)

Response

Success (201):

{
  "success": true,
  "assetId": "asset_abc123",
  "asset": { }
}

Errors:

Status	Body	Cause
400	{"error": "Invalid JSON body"}	Malformed request body
400	{"error": "Missing required fields: ..."}	Missing name, cdnUrl, mimeType, or sizeBytes
401	{"error": "Invalid webhook secret"}	Wrong secret
405	{"error": "Method not allowed"}	Not a POST request
503	{"error": "Webhook not configured..."}	WEBHOOK_SECRET env var not set

Example: cURL

curl -X POST https://your-webtrigger-url \
  -H "Content-Type: application/json" \
  -d '{
    "name": "logo.svg",
    "cdnUrl": "https://cdn.example.com/logo.svg",
    "mimeType": "image/svg+xml",
    "sizeBytes": 4096,
    "tags": ["logo", "brand"],
    "secret": "YOUR_WEBHOOK_SECRET"
  }'

Notes

• Assets registered via webhook start with approved: false and brandCompliance: pending
• The asset type is automatically determined from the MIME type
• Tags are normalized to lowercase and trimmed