### POST /api/v4/webhooks

**Create a webhook** (`create_webhook`). Register an HTTPS endpoint and the events it receives. The signing secret is returned once.

Free. API key required. Success: `201`. Accepts `Idempotency-Key`.

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Public HTTPS URL that receives POSTed events. |
| `label` | string \| null |  |  |
| `events` | array<string> |  | Event types to receive (default ["*"]). |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.url` | string \| null | yes |  |
| `data.label` | string \| null | yes |  |
| `data.api_version` | "v3" \| "v4" | yes |  |
| `data.events` | array<string> \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.signing_secret` | string |  | Returned on create and rotate only. |
| `data.previous_secret_valid_until` | string \| null |  |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/webhooks' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/startupseeker",
    "events": [
      "export.*",
      "enrichment.succeeded"
    ]
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```