---
title: "Create a webhook endpoint"
method: POST
path: "/webhook_endpoints"
tags: ["Webhook endpoints"]
---

# Create a webhook endpoint

`POST /webhook_endpoints`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/webhook_endpoints`
- Auth: API key in header `Authorization`

Registers a receiver for a workspace's events. The key must be an owner or admin of the
workspace, and a workspace holds at most 10 endpoints.

The response is the only one that carries `secret`: store it to
[verify each request](/api-reference/webhooks#verification-code). Send your own `secret` to use
the same one everywhere; otherwise one starting with `whsec_` is generated. If you lose it,
delete the endpoint and create it again.

The endpoint is pinned to the API version this request was served at, unless you send
`api_version`. Its events are named and shaped as that version has them.

## Request body

- WebhookEndpointCreate
  - `metadata` union: Merged into the object's metadata: the keys you send are added or overwritten and the others kept. `""` as a value removes that key; `metadata: ""` removes every key. Numbers and booleans are stored as their text; objects, arrays and `null` are refused.
    - object
    - ''
  - `workspace_id` string, required: The workspace whose events it receives. A `wks_` id; integer workspace ids are still accepted.
  - `url` string, required: A public HTTPS URL. Redirects are not followed.
  - `enabled_events` string[], required: Event types, or `*` for every event this workspace and version send, now and later.
  - `name` string, nullable: Defaults to the URL's host.
  - `secret` string, nullable: Your own signing secret, at least 16 characters. Omit it to have one generated.
  - `api_version` string: Pin the endpoint to this version instead of the one serving the request.

## Response `201`

Endpoint created, with its `secret`.

- object
  - `id` string: Webhook endpoint ID, beginning with `whe_`. Treat it as an opaque string.
  - `object` string: Always `webhook_endpoint`.
  - `workspace_id` string: Workspace ID, beginning with `wks_`. Treat it as an opaque string.
  - `name` string: Defaults to the URL's host.
  - `url` string, uri: The public HTTPS URL events are sent to.
  - `enabled_events` string[]: The events it receives, named as its `api_version` names them. `*` is every event.
  - `status` 'enabled' | 'disabled': Whether it receives events. - `enabled`: receives events. - `disabled`: receives nothing; disabling cancels its pending deliveries.
  - `api_version` string, date: The version its events are named and shaped at.
  - `metadata` Metadata: Your own key-value pairs, for your ids and context. HappyScribe stores them, returns them on the object and in every webhook that carries it, and never acts on them. Up to 50 keys of up to 40 characters (no square brackets), values up to 500 characters. See [metadata](/meetingkit/setup#a-workspace-per-customer).
  - `created_at` string, date-time: When it was created, in ISO 8601.
  - `updated_at` string, date-time: When it last changed, in ISO 8601.
  - `secret` string, required: The signing secret. Shown only in this response.

## Other responses

- `400`: `workspace_id` is not a single id.
- `401`: Your API key is missing (`missing_api_key`) or wrong (`invalid_api_key`), or it may not access this resource (`unauthorized`).
- `403`: The key is not an owner or admin of the workspace (`workspace_update_not_allowed`).
- `404`: `workspace_id` is not a workspace the key belongs to.
- `422`: A field failed validation: an unsafe or invalid `url`, a `secret` under 16 characters (`secret_too_short`), an event this workspace or API version does not send (`unsupported_event`, whose message lists the ones it does), or the workspace already has 10 endpoints (`limit_reached`).

---

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