---
title: "Create hook"
method: POST
path: "/hooks"
tags: ["hooks"]
---

# Create hook

`POST /hooks`

## Request body

- DomainHook
  - `batch_flush_interval_sec` integer — BatchFlushIntervalSec is the maximum time a batch may sit before being flushed even when below BatchMaxItems. 0 = use HooksConfig default, then DefaultHookBatchFlushIntervalSec.
  - `batch_max_items` integer — BatchMaxItems caps the number of events bundled into one HTTP POST body. 0 = use HooksConfig.BatchMaxItems, then DefaultHookBatchMaxItems. Ignored for File hooks (they always write one event per line).
  - `batch_max_queue_items` integer — BatchMaxQueueItems caps the per-hook in-memory queue (pending + re-queued failures). When exceeded, the OLDEST events are dropped with a warning log so the queue never grows unbounded against an unreachable target. 0 = use HooksConfig default, then DefaultHookBatchMaxQueueItems.
  - `enabled` boolean
  - `event_types` DomainEventType[] — EventTypes filters which events trigger delivery. Empty = all events.
  - `id` string
  - `max_retries` integer — MaxRetries is the number of delivery attempts before giving up. 0 means use the server default (3). For HTTP hooks this caps retries inside a single batch flush; events that still fail are re-queued for the next flush regardless of MaxRetries.
  - `metadata` object — Metadata holds user-defined key-value pairs merged into every event payload delivered by this hook. Useful for tagging events with custom context (e.g. environment, tenant ID, region) without modifying the server config.
  - `name` string
  - `secret` string — HMAC-SHA256 signing secret (HTTP only)
  - `stream_codes` DomainStreamCodeFilter
    - `except` string[] — Except delivers events for all streams except those in this list.
    - `only` string[] — Only delivers events only for streams in this list.
  - `target` string — HTTP(S) URL or absolute file path
  - `timeout_sec` integer — TimeoutSec is the per-attempt delivery timeout in seconds. 0 means use the server default (10s).
  - `type` 'http' | 'file'

## Response `201`

Created

- ApidocsHookData
  - `data` DomainHook
    - `batch_flush_interval_sec` integer — BatchFlushIntervalSec is the maximum time a batch may sit before being flushed even when below BatchMaxItems. 0 = use HooksConfig default, then DefaultHookBatchFlushIntervalSec.
    - `batch_max_items` integer — BatchMaxItems caps the number of events bundled into one HTTP POST body. 0 = use HooksConfig.BatchMaxItems, then DefaultHookBatchMaxItems. Ignored for File hooks (they always write one event per line).
    - `batch_max_queue_items` integer — BatchMaxQueueItems caps the per-hook in-memory queue (pending + re-queued failures). When exceeded, the OLDEST events are dropped with a warning log so the queue never grows unbounded against an unreachable target. 0 = use HooksConfig default, then DefaultHookBatchMaxQueueItems.
    - `enabled` boolean
    - `event_types` DomainEventType[] — EventTypes filters which events trigger delivery. Empty = all events.
    - `id` string
    - `max_retries` integer — MaxRetries is the number of delivery attempts before giving up. 0 means use the server default (3). For HTTP hooks this caps retries inside a single batch flush; events that still fail are re-queued for the next flush regardless of MaxRetries.
    - `metadata` object — Metadata holds user-defined key-value pairs merged into every event payload delivered by this hook. Useful for tagging events with custom context (e.g. environment, tenant ID, region) without modifying the server config.
    - `name` string
    - `secret` string — HMAC-SHA256 signing secret (HTTP only)
    - `stream_codes` DomainStreamCodeFilter
      - `except` string[] — Except delivers events for all streams except those in this list.
      - `only` string[] — Only delivers events only for streams in this list.
    - `target` string — HTTP(S) URL or absolute file path
    - `timeout_sec` integer — TimeoutSec is the per-attempt delivery timeout in seconds. 0 means use the server default (10s).
    - `type` 'http' | 'file'

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error

---

[API](https://skmtc.net/datvietvac-techhub/apis/open-streamer-api.md) · [All operations](https://skmtc.net/datvietvac-techhub/apis/open-streamer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datvietvac-techhub/open-streamer-api/revisions/9f723293b698/schema)