Create webhook

Interface Description

Create a webhook subscription and receive the signing secret once.

Endpoint

Field	Value
Method	POST
Path	/openapi/v2/webhooks
Operation ID	createWebhook
Authentication	Bearer OpenAPI key

Parameters

Name	Location	Required	Type	Example	Description
Idempotency-Key	header	Yes	string	mutation-2026-07-10-001	Client-generated key for safely retrying the same request. Reuse the same value for retries so duplicate work is not created.

Request Body

application/json

Field	Required	Type	Example	Description
name	No	string | null	Source file updates	Optional webhook name.
url	Yes	string	https://hooks.example.com/focowiki	Public HTTPS receiver URL. Loopback, private, link-local, reserved, credential-bearing, fragment-bearing, and redirect targets are rejected.
events	Yes	array<document.waiting | document.processing | document.available | document.error | document.deleting | file.deleted | knowledge_base.deleted>	["document.available","document.error","document.deleting"]	Webhook event types included in this subscription.

Request Example

curl -X POST "https://openapi.example.com/openapi/v2/webhooks" \
  -H "Authorization: Bearer <openapi-key>" \
  -H "Idempotency-Key: mutation-2026-07-10-001" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Source file updates",
  "url": "https://hooks.example.com/focowiki",
  "events": [
    "document.available",
    "document.error",
    "document.deleting"
  ]
}'

Successful Responses

201

New webhook subscription and its signing secret.

Field	Required	Type	Description
webhook	Yes	object	Webhook subscription returned by the request.
signingSecret	Yes	string	Returned only by this create operation. An identical idempotent replay returns the same value; list operations never return it.

Success Response Example

{
  "webhook": {
    "webhookId": "webhook-11111111-1111-4111-8111-111111111111",
    "name": "Source file updates",
    "endpointHost": "hooks.example.com",
    "events": [
      "document.available",
      "document.error",
      "document.deleting"
    ],
    "createdAt": "2026-06-17T00:00:00.000Z",
    "lastDeliveryAt": null
  },
  "signingSecret": "<webhook-signing-secret>"
}

Error Codes

The table below lists every error response documented for this operation.

HTTP Status	Error Code	Explanation
401	UNAUTHORIZED	The Bearer API key is missing, malformed, unknown, revoked, or deleted.
413	PAYLOAD_TOO_LARGE	The request body or requested file exceeds the size limit for this operation.
422	VALIDATION_ERROR	The request failed validation.
429	RATE_LIMITED	The request exceeded the configured rate limits.
500	INTERNAL_ERROR	The API encountered an internal error.
503	DATABASE_REPOSITORY_UNAVAILABLE	The data required by this operation is temporarily unavailable.

Next Steps

• List webhook deliveries