---
title: "Register a new-episode webhook endpoint"
method: POST
path: "/v1/episodes/subscriptions"
tags: ["Episodes"]
---

# Register a new-episode webhook endpoint

`POST /v1/episodes/subscriptions`

## Request

- Base URL: `https://brain.inite.ai`
- URL: `https://brain.inite.ai/v1/episodes/subscriptions`
- Auth: HTTP bearer

Registers an http(s) endpoint for `episodes_available` pushes (see the EpisodesAvailableEvent schema and the top-level webhooks section). The HMAC signing secret is returned exactly once. Pushes carry METADATA ONLY — bodies are pulled through GET /v1/episodes under the subscriber’s own scopes. Delivery is at-least-once. 404 until EPISODE_SUBSCRIPTIONS_ENABLED=1.

Required scope: `brain:admin`.

## Request body

- CreateEpisodeSubscriptionRequest
  - `url` string, required

## Response `201`

Registered; store the secret now.

- CreateEpisodeSubscriptionResponse
  - `id` string, required
  - `secret` string, required
  - `watermark` string, required

## Other responses

- `400`: Validation failed.
- `401`: Missing or unknown bearer key.
- `403`: The key lacks the required scope.
- `404`: No such resource in this tenant.

---

[API](https://skmtc.dev/inite/apis/inite-brain-platform-api.md) · [All operations](https://skmtc.dev/inite/apis/inite-brain-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inite/apis/inite-brain-platform-api/revisions/c7c3eb5e304b?raw)