Skip to main content

​
Webhooks

Webhooks provide real-time push notifications when commentary approval events occur, eliminating the need for polling.

​
Benefits

  • Near real-time updates: Receive notifications within seconds of approval events
  • Reduced polling: No need to repeatedly check status endpoints
  • Reliable delivery: Automatic retries with exponential backoff
  • Secure: HMAC-SHA256 signed payloads

​
Event Types

EventDescription
creator.approvedCreator has approved their commentary — ready for partner review
partner.approvedPartner has approved the commentary — ready for distribution
commentary.failedCommentary generation failed or was rejected

​
Webhook Payload Structure

{
  "id": "evt_abc123",
  "type": "creator.approved",
  "created_at": "2026-02-04T10:00:00Z",
  "data": {
    "topic_id": "uuid",
    "external_reference": "your-content-id",
    "persona_id": "uuid",
    "persona_name": "Persona Name",
    "commentary": {
      "id": "uuid",
      "content": "The commentary text...",
      "audio_url": "https://cdn.unleeshed.ai/audio/...",
      "video_url": null
    },
    "metadata": {
      "your": "custom data"
    }
  }
}

​
Security

All webhook payloads are signed with HMAC-SHA256. The signature is included in the X-Unleeshed-Signature header: 
X-Unleeshed-Signature: t=1707000000,v1=5f2b...
See Webhook Integration Guide for verification code.

​
Required Scopes

  • webhooks:manage - Create, update, delete webhooks
  • webhooks:read - List webhooks and delivery logs

​
Next Steps

Register Webhook

Create your first webhook

Integration Guide

Complete setup instructions