# Create a webhook

### Create a webhook

`POST /api/v1/webhooks`

Operation ID: `createWebhook`

Every outbound event is sent to each of the organization's webhooks, signed with that webhook's secret. Up to 5 per organization. See [Webhooks](https://needle.app/docs/webhooks) for the request body, headers, signature checks, and retries.

**Request body** (required)

- `url` (string · uri, required): An https URL that accepts POST requests.

**201**: Webhook created. The response carries the secret.

- `webhook` (object, required)
  - `id` (string · uuid, required)
  - `url` (string, required)
  - `lastAttemptAt` (string · date-time | null, required)
  - `lastError` (string | null, required): Why the last failed delivery failed, for example 401. Null once a delivery succeeds.
  - `createdAt` (string · date-time, required)
  - `createdBy` (string · uuid | null, required)
- `secret` (string, required): The signing secret, whsec_…. Returned only here, when the webhook is created, and never again.
- `requestId` (string · uuid, required): Id of this request, for support and troubleshooting

**Errors**

- `400`: Bad request
- `401`: Unauthorized: missing or invalid API key
- `403`: Forbidden
- `404`: Not found
- `409`: The organization already has 5 webhooks.
- `422`: Invalid request payload