Webhooks

POST notifications when clip lifecycle events occur.

Set a webhook URL when creating a clip via the API (webhook field) or from clip settings in the UI. Webklip sends a JSON POST to your URL when the clip is read, burned, or expired.

Payload

{
  "event": "read",
  "slug": "my-clip",
  "timestamp": "2026-07-07T12:00:00.000Z",
  "viewCount": 2,
  "burnOnRead": false,
  "maxViews": 3,
  "burned": false
}

Events

• read — the clip was read via the API (after view counting)
• burned — the clip was deleted by burn-on-read or a view limit
• expired — the clip TTL elapsed and cleanup removed it

For burn events, burned in the payload is true. Additional fields may be included depending on the event.

Delivery

• Method: POST
• Content-Type: application/json
• User-Agent: Webklip-Webhook/1.0
• Timeout: 10 seconds

Webhook URLs must be public http or https endpoints. Private and loopback addresses are rejected to prevent server-side request forgery.

Example

curl -X POST https://webklip.com/api/v1/clips/alert \
  -H "Content-Type: application/json" \
  -d '{
    "content": "deploy token",
    "burnOnRead": true,
    "webhook": "https://hooks.example.com/webklip"
  }'