---
title: "设置该 Key 的完成回调 / Set the key's completion webhook"
method: PUT
path: "/v1/api-keys/{id}/webhook"
tags: ["Keys"]
---

# 设置该 Key 的完成回调 / Set the key's completion webhook

`PUT /v1/api-keys/{id}/webhook`

## Request

- Base URL: `https://api.musicsforyou.com`
- URL: `https://api.musicsforyou.com/v1/api-keys/{id}/webhook`
- Auth: OAuth 2 (authorization code, authorization URL `https://www.musicsforyou.com/oauth/authorize`, token URL `https://api.musicsforyou.com/oauth/token`, scopes: `music`)

作品到达终态（finished / failed）时向 `url` POST JSON `{ event: "generation.finished", generation }`，请求头 `X-Taoyuan-Signature: sha256=<HMAC-SHA256(body, 该 Key 的 webhook secret)>`。传 `null` 关闭。

When a generation started with this key reaches a terminal state, we POST `{ event: "generation.finished", generation }` to `url` with header `X-Taoyuan-Signature: sha256=<hex HMAC-SHA256 of the raw body using the key's webhook secret>`. Send `null` to turn it off.

## Path parameters

- `id` string, required

## Request body

- WebhookRequest
  - `url` string, uri, nullable, required: HTTPS 地址；null 表示关闭 / HTTPS URL, or null to turn off

## Response `200`

OK

- WebhookResponse
  - `success` true, required
  - `webhookUrl` string, uri, nullable, required

## Other responses

- `400`: 参数不合法 / Invalid parameters（code: INVALID_PARAMS 或 SPEC_INVALID，details 为 diagnostics）
- `401`: 未登录或 Key 无效 / Not authenticated（LOGIN_REQUIRED、INVALID_API_KEY）
- `404`: 不存在 / Not found

---

[API](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api.md) · [All operations](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api/llms.txt) · [OpenAPI document](https://skmtc.dev/musicsforyou/apis/taoyuan-music-api/revisions/65b8919a4d82?raw)