kuroco-webhook-processing

Kuroco Webhook and Batch Processing Patterns

Best practices for Webhooks, batch processing, and external integration in Kuroco HeadlessCMS.

Documentation Reference: /kuroco-docs You can search and reference the official Kuroco documentation using the skill.

Table of Contents

• Batch Processing
• Internal API Calls
• External API Calls
• Trigger Processing
• External Service Integration → For details, see references/integrations.md

About Smarty Syntax: Batch processing and triggers are written in Smarty templates. For details on syntax and plugins, refer to the /kuroco-smarty-plugins skill.

Batch Processing

Overview

Batch processing is processing that is automatically executed at fixed intervals.

Execution frequency options:

Frequency	Use Case
Every 15 minutes	When frequent synchronization is required
Every 30 minutes	Near real-time processing
Every hour	Regular aggregation and updates
Daily (specified time)	Daily reports, backups

Use case

• CSV generation and integration to external systems
• Data import from external systems
• Log aggregation and statistical data calculation
• Regular email delivery
• GitHub Actions integration (deploy trigger)

Creating Batch Processing

Admin panel: [Operations] → [Batch Processing] → [Add]

Item	Description	Example
Title	Batch name	CSV Export Batch
Identifier	Unique identifier (alphanumeric)	csv_export
Execution frequency	Execution interval	Daily 03:00
Execution content	Written in Smarty syntax	See below

Internal API Calls

Basic Syntax

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='response'
}

Retrieving Content List

{assign var="queries" value=$dataSet.emptyArray}
{append var="queries" index="cnt" value=0}
{append var="queries" index="filter" value="topics_flg = 1"}

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='news_list'
}

{foreach from=$news_list.list item="news"}
  ID: {$news.topics_id}, タイトル: {$news.subject}
{/foreach}

Creating Content

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="subject" value="タイトル"}
{append var="body" index="contents" value="本文"}
{append var="body" index="topics_flg" value=1}

{api_internal
  endpoint='/rcms-api/1/news/insert'
  method='POST'
  member_id=1
  body=$body
  var='result'
}

External API Calls

Basic Syntax

{api_request
  url='https://api.example.com/endpoint'
  method='GET'
  headers=$headers
  body=$body
  var='response'
}

POST Request Example

{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Content-Type" value="application/json"}
{append var="headers" index="Authorization" value="Bearer YOUR_API_KEY"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="message" value="Hello"}

{api_request
  url='https://api.example.com/post'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}

Trigger Processing

Trigger on Content Update

Admin panel: [Content Definition] → [Trigger Settings]

Available events:

Event	Timing
On creation	After new content is created
On update	After content is updated
On deletion	After content is deleted
On publication	When publication status changes

Available variables:

{$topics.topics_id}      {* コンテンツID *}
{$topics.subject}        {* タイトル *}
{$topics.contents}       {* 本文 *}
{$topics.ymd}            {* 公開日 *}
{$topics.ext_col_01}     {* 拡張項目 *}

Trigger on form submission

Admin panel: [Form] → [Trigger settings]

{$inquiry.inquiry_id}    {* 回答ID *}
{$inquiry.name}          {* 名前 *}
{$inquiry.email}         {* メールアドレス *}
{$inquiry.message}       {* メッセージ *}

External service integration

Detailed integration patterns: references/integrations.md see

Slack notification

{assign var="message" value=$dataSet.emptyArray}
{append var="message" index="text" value="通知メッセージ"}

{slack_send
  webhook_url="https://hooks.slack.com/services/xxx/yyy/zzz"
  body=$message|@json_encode
}

Email notification

{send_mail
  to="recipient@example.com"
  subject="件名"
  body="本文"
}

GitHub Actions integration

{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Authorization" value="token YOUR_GITHUB_TOKEN"}
{append var="headers" index="Accept" value="application/vnd.github.v3+json"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="event_type" value="kuroco-update"}

{api_request
  url='https://api.github.com/repos/owner/repo/dispatches'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}

Best practices

Execution time considering load

• Set during time periods with low system load (late night/early morning)
• Limit large data processing to once per day
• Use pagination to split processing

Error handling

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  var='response'
}

{if $response.errors}
  {slack_send webhook_url="..." text="エラー: {$response.errors|@json_encode}"}
  {log message="エラー: {$response.errors|@json_encode}"}
{else}
  {log message="処理完了: {$response.pageInfo.totalCnt}件"}
{/if}

Timeout countermeasures

Split processing for large data:

{assign var="page" value=1}
{while true}
  {assign var="queries" value=$dataSet.emptyArray}
  {append var="queries" index="pageID" value=$page}
  {append var="queries" index="cnt" value=100}

  {api_internal endpoint='/rcms-api/1/news' method='GET' member_id=1 queries=$queries var='response'}

  {foreach from=$response.list item="item"}
    {* 処理 *}
  {/foreach}

  {if $page >= $response.pageInfo.totalPageCnt}{break}{/if}
  {assign var="page" value=$page+1}
{/while}

Related skills

• /kuroco-smarty-plugins - Smarty plugin/syntax reference (details of syntax used in batch processing and triggers)
• /kuroco-content-management - Content management
• /kuroco-api-integration - API design/implementation

Related documents

• docs/tutorials/how-to-use-batch.md - How to use batch processing
• docs/tutorials/auto-run-github-with-contents-update.md - GitHub Actions integration
• docs/tutorials/send-slack-notification-after-a-form-has-been-submitted.md - Slack notification
• docs/reference/trigger-variables.md - Trigger variables