# Register a webhook endpoint `POST /webhooks` **Required scope:** `webhooks:manage` Requires scope webhooks:manage. URLs must be HTTPS in production. The response includes the HMAC signing secret once. Events include document.created, upload.completed, upload.failed, certificate.generated, workspace.created. ## Request body Content type: `application/json` (required) | Field | Type | Required | Description | |---|---|---|---| | `url` | string | **yes** | | | `events` | array | **yes** | | | `description` | string | no | | ## Responses | Status | Meaning | |---|---| | `201` | Webhook created; body includes the signing secret (shown once) | | `400` | BadRequest | ## Example ```bash curl -X POST "https://backend.immut.io/api/v1/webhooks" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"","events":"","description":""}' ``` ## OpenAPI fragment ```json { "/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint", "description": "Requires scope webhooks:manage. URLs must be HTTPS in production. The response includes the HMAC signing secret once. Events include document.created, upload.completed, upload.failed, certificate.generated, workspace.created.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Webhook created; body includes the signing secret (shown once)" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage" } } } ```