# Create a webhook endpoint — Shorty API

> Registers an HTTPS endpoint for job events and returns it with its `whsec_` signing secret, which is shown only in this response. Shorty immediately POSTs a signed `ping` event to the URL; a 2xx answer sets `verified_at`, and only verified endpoints receive events. A URL that is not public HTTPS on port 443 is refused with 400 `validation_failed`; an account already at its endpoint limit gets 429 `quota_exhausted`.

```http
POST /v1/webhook-endpoints
```

Registers an HTTPS endpoint for job events and returns it with its `whsec_` signing secret, which is shown only in this response. Shorty immediately POSTs a signed `ping` event to the URL; a 2xx answer sets `verified_at`, and only verified endpoints receive events. A URL that is not public HTTPS on port 443 is refused with 400 `validation_failed`; an account already at its endpoint limit gets 429 `quota_exhausted`.

## Authentication

Requires a Bearer credential — a `shk_live_` API key or an OAuth 2.1 access token with the scope for this resource. See [Authentication](/docs/api).

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes | A public HTTPS URL on port 443. Private, loopback and metadata addresses are refused. (1–2048 chars) |
| `event_types` | `"job.succeeded" \| "job.failed"[]` | Yes | The events to deliver (at least one). |
| `description` | `string` | No | Your label for the endpoint. (≤ 200 chars) |

## Example request

curl:

```bash
curl -X POST https://aishorty.com/v1/webhook-endpoints \
  -H "Authorization: Bearer shk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/shorty",
    "event_types": [
      "job.succeeded"
    ]
  }'
```

TypeScript (@aishorty/sdk):

```typescript
import { Shorty } from '@aishorty/sdk'

const shorty = new Shorty({ apiKey: process.env.SHORTY_API_KEY })

const { data } = await shorty.request({
    method: 'POST',
    path: '/v1/webhook-endpoints',
})
```

## Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `endpoint` | `WebhookEndpoint` | Yes | — |
| `secret` | `string` | Yes | The endpoint’s `whsec_` signing secret. Returned only here: store it to verify the `webhook-signature` header of every delivery. |

## Errors

On failure this endpoint returns an RFC 9457 problem body. Possible statuses:

- `400`
- `401`
- `403`
- `404`
- `429`
- `500`

Switch on the problem `code`, not the status. See the [error reference](/docs/api/errors) for every code and how to fix it.