---
title: "Register a minted webhook URL at an HTTPS destination without exposing the credential."
method: POST
path: "/v1/webhooks/apply"
tags: ["webhooks"]
---

# Register a minted webhook URL at an HTTPS destination without exposing the credential.

`POST /v1/webhooks/apply`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/webhooks/apply`
- Auth: HTTP bearer

Register a minted webhook URL at an HTTPS destination without exposing the credential. Pass the handle from webhookUrlMint, webhookUrlRotate, or webhookList. Destination type http performs an outbound HTTPS request and substitutes {{webhookUrl}} (and optional {{webhookSecret}} — package-owned HMAC from the webhook URL record, or a verification.secretName copied onto that record at mint or rotate) server-side into url/headers/body — interactive MCP only, and only after the owner Approves the exact destination via the same account approval flow as /connect/secrets host approval (approval_url → website Allow → durable grant → retry). Package-owned HMAC is not a user secrets-list entry and never needs a secret→host Allow; destination.secretName Bearer auth does. For GitHub repository hooks, POST https://api.github.com/repos/{owner}/{repo}/hooks with User-Agent kody, {{webhookUrl}} in config.url, {{webhookSecret}} in config.secret when HMAC is declared (omit verification.secretName so mint stores package-owned HMAC), and integration "github" (or a host-approved token). Returns ok, remote_id, and url_host only — never the credential URL or signing secret.

Org permission: `package:write`.

## Request body

- object
  - `handle` string, required: Opaque handle from webhookUrlMint, webhookUrlRotate, or webhookList.
  - `destination` object, required
    - `type` 'http', required
    - `url` string, required: HTTPS registration endpoint. May include {{webhookUrl}} and {{webhookSecret}} for server-side injection.
    - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE': HTTP method. Defaults to POST.
    - `headers` object: Optional request headers. Values may include {{webhookUrl}} and {{webhookSecret}}.
    - `body` string: Optional request body template. May include {{webhookUrl}} and {{webhookSecret}}.
    - `integration` string: Optional OAuth integration whose access token is sent as Authorization Bearer. Host must be allowed on the integration.
    - `secretName` string: Optional host-approved secret sent as Authorization Bearer. Host must be approved for the destination URL.

## Response `200`

Success.

- object
  - `ok` boolean, required
  - `url_host` string, required
  - `http_status` integer, required
  - `remote_id` string, nullable, required
  - `error` string, nullable, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

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