---
title: "Create a new Webhook"
method: POST
path: "/orgs/{orgId}/apps/{appId}/webhooks"
tags: ["public", "Event"]
---

# Create a new Webhook

`POST /orgs/{orgId}/apps/{appId}/webhooks`

## Path parameters

- `orgId` string, required
- `appId` string, required

## Request body

- WebhookCreateRequest — WebhookCreate is the request body for creating a webhook.
  - `disabled` boolean, nullable — Defines whether this job is currently disabled.
  - `headers` JSONFieldRequest
  - `id` string — Job ID, unique within the Organization
  - `payload` JSONFieldRequest
  - `secret_headers` SecretHeadersRequest — SecretHeaders maps header names to their secret values.
  - `triggers` EventBaseRequest[] — A list of Events by which the Job is triggered
    - `scope` string — Event scope
    - `type` string — Event type
  - `url` string, nullable — The webhook's URL (without protocol, only HTTPS is supported).

## Response `201`

A created webhook.

- WebhookResponse — Webhook is a special type of a Job. It performs an HTTPS request to a specified URL with specified headers.
  - `created_at` string — The timestamp of when this Job was created.
  - `created_by` string — The user who created this Job
  - `disabled` boolean, nullable, required — Defines whether this job is currently disabled.
  - `headers` JSONFieldResponse, required
  - `id` string, required — Job ID, unique within the Organization
  - `payload` JSONFieldResponse, required
  - `secret_headers` string[], required — The names of the webhook's secret HTTP headers.
  - `triggers` EventBaseResponse[], required — A list of Events by which the Job is triggered
    - `scope` string, required — Event scope
    - `type` string, required — Event type
  - `url` string, nullable, required — The webhook's URL (without protocol, only HTTPS is supported).

## Other responses

- `400` — Some of the values supplied are invalid.
- `409` — The supplied `id` clashes with an existing Job.

## Changes

- **2026-08-31** `3980a71317ca` — 2 info
  - added the new optional request property `secret_headers`
  - added the required property `secret_headers` to the response with the `201` status

[Change history](https://skmtc.dev/humanitec/apis/humanitec-api/changes/orgs/:orgId/apps/:appId/webhooks/post.md)

---

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