---
title: "Create webhook"
method: POST
path: "/api/settings/webhooks"
tags: ["webhooks"]
---

# Create webhook

`POST /api/settings/webhooks`

## Request body

- object
  - `watched` object[], required
    - `type` 'dataset' | 'model' | 'space' | 'bucket' | 'kernel' | 'user' | 'org', required
    - `name` string, required
  - `url` string, uri
  - `job` union
    - object
      - `spaceId` string, required
      - `dockerImage` string
      - `arguments` string[]
      - `command` string[]
      - `environment` object
      - `secrets` object
      - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
      - `arch` 'amd64' | 'arm64'
      - `timeoutSeconds` integer, nullable
      - `attempts` integer — Max number of attempts to make. For example, if you set this to 3, the job will be retried up to 2 times if it fails.
      - `labels` object — Labels for the job as key-value pairs. Both keys and values must be max 100 characters and contain only alphanumeric characters, dots, dashes, and underscores.
      - `volumes` object[] — HuggingFace Buckets or Repos to mount as volumes in the job container.
        - `type` 'bucket' | 'model' | 'dataset' | 'space', required
        - `source` string, required — Source identifier, e.g. 'username/my-bucket' or 'username/my-model'
        - `mountPath` string, required — Mount path inside the container, e.g. '/data'
        - `revision` string — Git revision (only for repos, defaults to 'main')
        - `readOnly` boolean — Read-only mount (true for repos, false default for buckets)
        - `path` string — Subfolder prefix inside the bucket/repo to mount, e.g. 'path/to/dir'
      - `expose` object — Ports to expose publicly through the jobs proxy. Each port is reachable at `https://<job_id>--<port>.<jobs-public-domain>`. Access requires a HF token with read access to the job's namespace, except for ports also listed in `portsPublic`.
        - `ports` integer[], required
        - `portsPublic` integer[] — Subset of `ports` reachable without any authentication.
      - `ssh` object — When `enabled`, the job's container is reachable over SSH at `ssh <job_id>@ssh.hf.jobs`. Only the job's owner is allowed in, authenticated by an SSH public key registered on the Hub.
        - `enabled` boolean
      - `network` object — Opt-in network group. Jobs of the same owner and resource group sharing a group are placed together and reach each other on every port. Two environment variables are set in the container: `HF_NETWORK_GROUP_HOSTNAME`, a hostname resolving to every member of the group, and `HF_NETWORK_GROUP_PREFIX`, to which an alias is appended to get that alias' hostname.
        - `group` string, required — Group name, scoped to the job's owner and resource group.
        - `aliases` string[] — Roles this job answers to. An alias names a role, not a job: several members may claim the same alias, which then resolves to all of them, and a member may claim several. Peers get the hostname by appending the alias to the `HF_NETWORK_GROUP_PREFIX` environment variable, which already ends with a separator.
      - `resourceGroupId` string
    - object
      - `spaceId` string
      - `dockerImage` string, required
      - `arguments` string[]
      - `command` string[]
      - `environment` object
      - `secrets` object
      - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
      - `arch` 'amd64' | 'arm64'
      - `timeoutSeconds` integer, nullable
      - `attempts` integer — Max number of attempts to make. For example, if you set this to 3, the job will be retried up to 2 times if it fails.
      - `labels` object — Labels for the job as key-value pairs. Both keys and values must be max 100 characters and contain only alphanumeric characters, dots, dashes, and underscores.
      - `volumes` object[] — HuggingFace Buckets or Repos to mount as volumes in the job container.
        - `type` 'bucket' | 'model' | 'dataset' | 'space', required
        - `source` string, required — Source identifier, e.g. 'username/my-bucket' or 'username/my-model'
        - `mountPath` string, required — Mount path inside the container, e.g. '/data'
        - `revision` string — Git revision (only for repos, defaults to 'main')
        - `readOnly` boolean — Read-only mount (true for repos, false default for buckets)
        - `path` string — Subfolder prefix inside the bucket/repo to mount, e.g. 'path/to/dir'
      - `expose` object — Ports to expose publicly through the jobs proxy. Each port is reachable at `https://<job_id>--<port>.<jobs-public-domain>`. Access requires a HF token with read access to the job's namespace, except for ports also listed in `portsPublic`.
        - `ports` integer[], required
        - `portsPublic` integer[] — Subset of `ports` reachable without any authentication.
      - `ssh` object — When `enabled`, the job's container is reachable over SSH at `ssh <job_id>@ssh.hf.jobs`. Only the job's owner is allowed in, authenticated by an SSH public key registered on the Hub.
        - `enabled` boolean
      - `network` object — Opt-in network group. Jobs of the same owner and resource group sharing a group are placed together and reach each other on every port. Two environment variables are set in the container: `HF_NETWORK_GROUP_HOSTNAME`, a hostname resolving to every member of the group, and `HF_NETWORK_GROUP_PREFIX`, to which an alias is appended to get that alias' hostname.
        - `group` string, required — Group name, scoped to the job's owner and resource group.
        - `aliases` string[] — Roles this job answers to. An alias names a role, not a job: several members may claim the same alias, which then resolves to all of them, and a member may claim several. Peers get the hostname by appending the alias to the `HF_NETWORK_GROUP_PREFIX` environment variable, which already ends with a separator.
      - `resourceGroupId` string
  - `jobSourceId` string
  - `domains` string[], required
  - `secret` string

## Response `200`

Created webhook

- object
  - `webhook` object, required
    - `id` string, required — A hex string of 24 characters representing an ObjectId.
    - `url` string, uri
    - `job` union
      - object
        - `dockerImage` string
        - `spaceId` string, required
        - `environment` object, required
        - `arguments` string[]
        - `command` string[]
        - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
        - `timeoutSeconds` integer, nullable, required
        - `labels` object — Labels for the job as key-value pairs. Both keys and values must be max 100 characters and contain only alphanumeric characters, dots, dashes, and underscores.
        - `secrets` string[]
      - object
        - `dockerImage` string, required
        - `spaceId` string
        - `environment` object, required
        - `arguments` string[]
        - `command` string[]
        - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
        - `timeoutSeconds` integer, nullable, required
        - `labels` object — Labels for the job as key-value pairs. Both keys and values must be max 100 characters and contain only alphanumeric characters, dots, dashes, and underscores.
        - `secrets` string[]
    - `jobSourceId` string
    - `disabled` union, required
      - boolean
      - 'suspended-after-failure'
    - `watched` object[], required
      - `name` string, required
      - `type` 'dataset' | 'model' | 'space' | 'bucket' | 'kernel' | 'user' | 'org', required
      - `avatarUrl` string
    - `hasSecret` boolean, required — Whether the webhook has a secret (the secret itself is never returned)
    - `domains` string[], required
    - `lastTriggerAt` string, date-time

## Changes

- **2026-09-11** `c447fcdd4d16` — 1 breaking, 1 info
  - removed `subschema #1, subschema #2` from the `job` request property `oneOf` list
  - added `subschema #1, subschema #2` to the `job` request property `oneOf` list
- **2026-09-08** `bd17546f47b8` — 11 breaking, 21 warning, 2 info
  - the `domains/items/` request property type changed from no type to `string`
  - the `job` request property type changed from `object` to no type
  - the `watched/items/type` request property type changed from no type to `string`
  - added `subschema #1, subschema #2` to the `webhook/job` response property `oneOf` list for the response status `200`
  - …30 more
- **2026-07-31** `c3e0c48d4112` — 1 warning, 1 info
  - removed the optional property `webhook/secret` from the response with the `200` status
  - added the required property `webhook/hasSecret` to the response with the `200` status
- **2026-07-27** `05ebd27557fb` — 1 info
  - added the new optional request property `job/resourceGroupId`
- **2026-07-26** `36390f25f00f` — 1 info
  - added the new optional request property `job/expose/portsPublic`

[Change history](https://skmtc.dev/huggingface/apis/hub-api-endpoints/changes/api/settings/webhooks/post.md)

---

[API](https://skmtc.dev/huggingface/apis/hub-api-endpoints.md) · [All operations](https://skmtc.dev/huggingface/apis/hub-api-endpoints/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingface/apis/hub-api-endpoints/revisions/68387ea03846?raw)