Skip to main content

​
Payload envelope

Every webhook delivery wraps the event-specific data in a standard envelope: 
{
  "event": "content.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-5d2b-71e7-90f4-4b8bd1cfe98b",
  "is_test": false,
  "data": {
    // Event-specific payload — see below
  }
}
FieldTypeDescription
eventstringThe event type that triggered this delivery
timestampstringISO 8601 timestamp of when the event was sent
workspace_iduuidThe workspace where the event originated
is_testbooleantrue if this was sent via the test endpoint
dataobjectEvent-specific payload (see sections below)

​
Content events

​
content.status_updated

Fires when an article’s status changes (e.g., draft to published, processing to generated). 
{
  "event": "content.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "9f2a3b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "title": "10 Strategies for Content Marketing in 2026",
    "buyer_stage": "awareness",
    "metadata": {
      "topic": "Content Marketing",
      "keywords": ["content strategy", "marketing"],
      "source": "TOPIC_CLUSTERS"
    },
    "status": "GENERATED",
    "config": {
      "autowrite": false,
      "planned_for": null,
      "planned_time": null
    },
    "written_on": "2026-04-16T10:25:00+00:00",
    "published_on": null,
    "research_batch_id": "8e1d2c3b-...",
    "topic": "Content Marketing",
    "keywords": ["content strategy", "marketing"],
    "source": "TOPIC_CLUSTERS",
    "body": "<p>Article HTML content...</p>",
    "cover_image": "https://cdn.deepsmith.io/images/cover.jpg",
    "slug": "content-marketing-strategies-2026",
    "permalink": "/blog/content-marketing-strategies-2026",
    "meta_title": "10 Content Marketing Strategies for 2026",
    "meta_description": "Learn the top content marketing strategies...",
    "post_url": "https://your-site.com/blog/content-marketing-strategies-2026",
    "createdAt": "2026-04-15T08:00:00+00:00",
    "updatedAt": "2026-04-16T10:30:00+00:00"
  }
}
FieldTypeDescription
iduuidContent ID
titlestringArticle title
buyer_stagestring|nullFunnel stage (awareness, consideration, decision)
metadataobjectTopic, keywords, and source metadata
statusstringCurrent status (e.g., DRAFT, PROCESSING, GENERATED, PUBLISHED, FAILED)
configobjectAutowrite and scheduling configuration
written_ondatetime|nullWhen the content was generated
published_ondatetime|nullWhen the content was published
research_batch_iduuid|nullAssociated research batch
bodystring|nullFull HTML content body
cover_imagestring|nullCover image URL
slugstring|nullURL slug
permalinkstring|nullRelative permalink
meta_titlestring|nullSEO title
meta_descriptionstring|nullSEO description
post_urlstring|nullPublished URL on your site

​
Research events

​
research_batch.status_updated

Fires when a research batch completes processing or fails. 
{
  "event": "research_batch.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "8e1d2c3b-4a5f-6c7d-8e9f-0a1b2c3d4e5f",
    "name": "Q2 Content Ideas",
    "ideas_count": 15,
    "status": "COMPLETED",
    "topic_id": "7d0e1f2a-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
    "topic_name": "Content Marketing",
    "buyer_stage": "awareness",
    "persona_name": "Marketing Manager",
    "source": "TOPIC_CLUSTERS",
    "agent_log": [],
    "research_log": null,
    "ideas": [],
    "createdAt": "2026-04-16T09:00:00+00:00",
    "updatedAt": "2026-04-16T10:30:00+00:00"
  }
}
FieldTypeDescription
iduuidResearch batch ID
namestringBatch name
ideas_countintegerNumber of ideas generated
statusstringBatch status (e.g., QUEUED, PROCESSING, COMPLETED, FAILED)
topic_iduuidAssociated topic cluster ID
topic_namestringTopic name
buyer_stagestring|nullFunnel stage
persona_namestring|nullTarget persona
sourcestringResearch source
ideasarrayGenerated content ideas

​
Agent events

​
agent_task.status_updated

Fires when an AI agent task changes state (queued, running, succeeded, failed). 
{
  "event": "agent_task.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "6c5d4e3f-2a1b-0c9d-8e7f-6a5b4c3d2e1f",
    "agent_id": "5b4c3d2e-1f0a-9b8c-7d6e-5f4a3b2c1d0e",
    "agent": {
      "id": "5b4c3d2e-1f0a-9b8c-7d6e-5f4a3b2c1d0e",
      "name": "Content Writer",
      "icon": "pencil",
      "short_description": "Writes long-form SEO content"
    },
    "name": "Write article: Content Marketing Strategies",
    "status": "SUCCEEDED",
    "inputs": {},
    "outputs": null,
    "usage": {
      "input_tokens": 4250,
      "output_tokens": 8100,
      "total_tokens": 12350
    },
    "execution_duration": 45200,
    "started_at": "2026-04-16T10:29:15+00:00",
    "ended_at": "2026-04-16T10:30:00+00:00",
    "created_at": "2026-04-16T10:29:10+00:00"
  }
}
FieldTypeDescription
iduuidAgent task ID
agent_iduuidParent agent ID
agentobjectAgent details (id, name, icon, short_description)
namestringTask name
statusstringTask status (QUEUED, RUNNING, SUCCEEDED, FAILED)
inputsobjectTask input parameters
outputsobject|nullTask output data
usageobjectToken usage (input_tokens, output_tokens, total_tokens)
execution_durationinteger|nullExecution time in milliseconds
started_atdatetime|nullWhen execution started
ended_atdatetime|nullWhen execution completed

​
Topic events

​
topic.status_updated

Fires when a topic cluster’s stage changes (e.g., processing to ready). 
{
  "event": "topic.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "7d0e1f2a-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
    "name": "Content Marketing",
    "stage": "READY",
    "keywords": [
      {"keyword": "content strategy", "msv": 5400, "kd": 45},
      {"keyword": "content marketing", "msv": 12000, "kd": 62}
    ],
    "totalMsv": 17400,
    "msvBadge": "MEDIUM",
    "avgKd": 53,
    "kdBadge": "MEDIUM",
    "coverage": 75,
    "createdAt": "2026-04-10T08:00:00+00:00",
    "updatedAt": "2026-04-16T10:30:00+00:00"
  }
}
FieldTypeDescription
iduuidTopic cluster ID
namestringTopic name
stagestringCurrent stage (e.g., PROCESSING, READY, COMPLETED)
keywordsarrayAssociated keywords with search volume and difficulty
totalMsvintegerTotal monthly search volume
msvBadgestringSearch volume tier (LOW, MEDIUM, HIGH)
avgKdintegerAverage keyword difficulty
kdBadgestringDifficulty tier (LOW, MEDIUM, HIGH)
coverageintegerContent coverage percentage

​
IQ events

​
iq.status_updated

Fires when an IQ analysis (persona, product brief, voice profile) completes or changes stage. 
{
  "event": "iq.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "4a3b2c1d-0e9f-8a7b-6c5d-4e3f2a1b0c9d",
    "type": "persona",
    "title": "Marketing Manager Persona",
    "description": "B2B SaaS marketing manager, 5-10 years experience",
    "content": "...",
    "metadata": {},
    "productId": null,
    "productUrls": null,
    "voiceSampleUrls": null,
    "contentSampleUrls": null,
    "isDefault": false,
    "stage": "READY",
    "imagesUrls": null,
    "createdAt": "2026-04-15T14:00:00+00:00",
    "updatedAt": "2026-04-16T10:30:00+00:00"
  }
}
FieldTypeDescription
iduuidIQ record ID
typestringIQ type (e.g., persona, product, voice)
titlestringIQ title
descriptionstring|nullDescription
contentstring|nullGenerated content
metadataobjectAdditional metadata
stagestringCurrent stage (e.g., PROCESSING, READY)
isDefaultbooleanWhether this is the default for its type

​
Sitemap events

​
sitemap_url.status_updated

Fires when sitemap URL processing completes or fails. 
{
  "event": "sitemap_url.status_updated",
  "timestamp": "2026-04-16T10:30:00+00:00",
  "workspace_id": "019d917f-...",
  "is_test": false,
  "data": {
    "id": "3f2e1d0c-9b8a-7f6e-5d4c-3b2a1f0e9d8c",
    "url": "https://your-site.com/sitemap.xml",
    "type": "sitemap",
    "urlCount": 142,
    "lastFetchedAt": "2026-04-16T10:30:00+00:00",
    "createdAt": "2026-04-14T09:00:00+00:00",
    "updatedAt": "2026-04-16T10:30:00+00:00",
    "processing": {
      "total": 142,
      "ready": 138,
      "failed": 4,
      "completed": true
    }
  }
}
FieldTypeDescription
iduuidSitemap URL record ID
urlstringSitemap URL
typestringURL type (sitemap, page)
urlCountintegerNumber of URLs in sitemap
lastFetchedAtdatetimeLast fetch timestamp
processingobjectProcessing stats (total, ready, failed, completed)

​
Event catalog endpoint

You can fetch the list of available events programmatically: 
GET /api/workspace/{workspace_id}/webhooks/events

{
  "code": 8010,
  "messages": "Event catalog retrieved successfully",
  "data": [
    {
      "event": "content.status_updated",
      "label": "Content Status Updated",
      "description": "Fires when an article's status changes (e.g., draft to published)",
      "group": "content"
    },
    {
      "event": "research_batch.status_updated",
      "label": "Research Batch Status Updated",
      "description": "Fires when a research batch completes or fails",
      "group": "research_batch"
    }
  ]
}