---
title: "Registers a webhook subscription (an instant-trigger endpoint)."
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks"]
---

# Registers a webhook subscription (an instant-trigger endpoint).

`POST /api/v1/webhooks`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/webhooks`
- Auth: HTTP bearer

Requires `ManageOrganizations` and an `Idempotency-Key` header. The response includes the
HMAC `signingSecret`<b>once</b> — store it to verify the `X-Flex-Signature-V2` (timestamped, replay-safe) and `X-Flex-Signature` headers; it is
never retrievable again. The URL must be a public `https` endpoint. Attributed to the key's
creator. Example: `{ "url": "https://hooks.zapier.com/…", "events": ["job.completed"] }`.

## Request body

- CreateWebhookSubscriptionRequest: Request body for `POST /api/v1/webhooks` (register an instant-trigger endpoint).
  - `url` string, nullable: The absolute `https` URL to POST events to. Public hosts only (no localhost/private ranges). Required.
  - `events` string[], nullable: The event names to subscribe to (at least one; see `GET /api/v1/webhooks/events`). Example: `["job.completed"]`.

## Response `201`

Created; `Location` points at the subscription. Body includes `signingSecret`.

- WebhookSubscriptionDto: A webhook subscription: the web host POSTs a signed JSON payload to `url` whenever one of the subscribed `events` occurs. Used by integration platforms (Zapier, Make) to register an instant-trigger endpoint per automation.
  - `id` integer: Numeric id of the subscription. Example: `42`.
  - `url` string: The absolute `https` URL that receives the event payloads.
  - `events` string[]: The subscribed event names (see `GET /api/v1/webhooks/events`). Example: `["job.completed","invoice.paid"]`.
  - `active` boolean: Whether the subscription is currently delivering. Auto-disables after repeated failures.
  - `createdAt` string, date-time: When the subscription was created, ISO-8601 UTC.
  - `signingSecret` string, nullable: The HMAC signing secret for verifying the `X-Flex-Signature-V2` (`t=<unix seconds>,v1=<hex>` over `"<t>.<raw body>"`) and legacy `X-Flex-Signature` headers. Returned <b>only</b> in the response to `POST /api/v1/webhooks` (shown once, never retrievable again); `null` otherwise.

## Other responses

- `400`: Malformed body or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: Forbidden
- `409`: The key's creator is unknown on this server.
- `422`: The URL or events are unacceptable; the field is listed in `errors`.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)