---
title: "Create a webhook"
method: POST
path: "/api/orgs/{slug}/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /api/orgs/{slug}/webhooks`

## Request

- Base URL: `https://trydock.ai`
- URL: `https://trydock.ai/api/orgs/{slug}/webhooks`
- Auth: HTTP bearer

Register a webhook subscription. The full signing secret is returned exactly once in the response — store it before the response is closed.

## Path parameters

- `slug` string, required

## Request body

- object
  - `url` string, uri, required
  - `events` string[]

## Response `200`

Created.

- object
  - `webhook` object, required
    - `id` string, required
    - `url` string, uri, required
    - `events` string[], required: Event names this webhook subscribes to. See `CreateWebhookSchema` for the canonical list.
    - `active` boolean, required
    - `secretPreview` string, required: First 8 chars of the signing secret. The full secret is only returned at create + rotate time.
    - `createdByPrincipalId` string, required
    - `createdByPrincipalType` 'user' | 'agent', required: Whether the actor is a human user or a Dock-managed agent.
    - `createdAt` string, date-time, required
    - `secret` string, required: The full signing secret. Returned ONCE at creation and on rotate-secret. Store it; it cannot be retrieved later.

## Other responses

- `400`: URL failed SSRF guard (loopback, private range, cloud metadata).

## Changes

- **2026-11-05** `767beae124a8`: 14 info
  - added the new `file.archived` enum value to the request property `events/items/`
  - added the new `file.commented` enum value to the request property `events/items/`
  - added the new `file.described` enum value to the request property `events/items/`
  - added the new `file.moved` enum value to the request property `events/items/`
  - …10 more

[Operation history](https://skmtc.dev/trydock/apis/dock-rest-api/changes/api/orgs/:slug/webhooks/post.md)

---

[API](https://skmtc.dev/trydock/apis/dock-rest-api.md) - [All operations](https://skmtc.dev/trydock/apis/dock-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trydock/apis/dock-rest-api/revisions/dd96ae96a412?raw)