---
title: "Mint (or remint) the URL secret for a package-declared webhook and return an opaque handle plus url_host."
method: POST
path: "/v1/webhooks/{webhookName}/url"
tags: ["webhooks"]
---

# Mint (or remint) the URL secret for a package-declared webhook and return an opaque handle plus url_host.

`POST /v1/webhooks/{webhookName}/url`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/webhooks/{webhookName}/url`
- Auth: HTTP bearer

Mint (or remint) the URL secret for a package-declared webhook and return an opaque handle plus url_host. Pass createInstance+instanceLabel to mint another URL under the same declared name (each URL needs its own Approve). The credential URL is never returned — register it with webhookUrlApply. Minting does not turn the webhook on: deliveries fail with enablement_not_on until a person opens approval_url and clicks Approve, which runs it as them (and is where its credentials are mapped). Existing approvals are kept across remint and rotate.

Org permission: `package:write`.

## Path parameters

- `webhookName` string, required: Webhook name from package.json#kody.webhooks[].name.

## Request body

- object
  - `packageId` string: Saved-package UUID. Use when the scoped name is not known, or for a stable ref.
  - `kodyId` string: Package name (`@owner/leaf` or the name leaf). Prefer this when you know the name.
  - `createInstance` boolean: When true, mint another URL under the same declared name. Requires instanceLabel.
  - `instanceLabel` string: Short label to tell this URL apart from others under the same name.

## Response `200`

Success.

- object
  - `webhook` object, required
    - `package_id` string, required
    - `package_kody_id` string, required
    - `name` string, required
    - `endpoint_id` string, required: Webhook endpoint id. The URL identity for this mint.
    - `instance_label` string, nullable, required: Short label when several URLs share the declared webhook name. Null on the first mint without a label.
    - `handle` string, required: Opaque handle for webhookUrlApply. Does not contain the URL secret.
    - `url_host` string, required: Public hostname of the ingress origin (no path or secret).
    - `enabled` boolean, required
    - `created_at` string, required
    - `rotated_at` string, required
    - `previous_url_active_until` string, nullable, required: ISO timestamp while the previous URL still accepts deliveries after rotate. Null on first mint.
    - `approval_url` string, nullable, required: Send this to the person: deliveries run only after they open it and click Approve. Null once the webhook is on (or paused) for someone.

## 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)