Add a webhook endpoint

POST /v1/webhook-endpoints · permission webhook-endpoints:write · all plans

Adds an endpoint that receives the environment's events, signed with the Standard Webhooks v1 scheme. Deliveries are at least once: deduplicate with the webhook-id header.

Signing secret. The response carries signing_secret (idp_whsec_…) once, with Cache-Control: no-store. It cannot be retrieved again; store it immediately. A request repeated with the same Idempotency-Key returns the endpoint without the secret and with secret_redacted: true. Use Rotate the signing secret if it is lost or leaked.
URL. https only, no port or port 443, no user info or fragment, no IP literal, at most 2,048 characters. Redirects are not followed.
Events. event_types lists catalog event types; an empty list means every type except the high-volume ones.
Limit. An environment can have at most Free 3, Startup 20, Business 20 or Enterprise 50 enabled endpoints.

Request

Field	Type	Required	Description
`url`	string	yes	Receiver URL (rules above).
`key`	string	no	Stable key, unique in the environment: `[a-z0-9][a-z0-9_-]{0,63}`. Default `endpoint-<last 8 characters of the id>`.
`description`	string	no	At most 500 characters.
`event_types`	array	no	Catalog event types, at most 100, no duplicates. Empty or absent: all types except high-volume ones.
`event_schema_versions`	object	no	Event type → schema version. A type not listed is sent with its oldest supported version.
`payload_mode`	string	no	`thin` (default: ids, changed field names and state fields, no personal data) or `full` (the management API representation of the resource).
`rate_limit_per_second`	integer	no	1–1,000 deliveries per second to this endpoint; default 50.
`status`	string	no	`enabled` (default) or `disabled_by_user`.
`Idempotency-Key`	header	no	Replays the response (without the secret) for a repeated request with the same key.

{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}

Response

201 Created with the endpoint, ETag set to its version, and the secret. The other fields are described in Get a webhook endpoint.

{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}

Errors

HTTP	code	When
400	`unknown_field`	The body has a field that is not listed above.
403	`quota_exceeded`	The environment already has its plan's number of enabled endpoints, or its plan is not known.
409	`conflict`	Another endpoint of the environment has this `key`.
422	`validation_failed`	`/url required`, `/url invalid_webhook_url`, `/key invalid`, `/description too_long`, `/event_types unknown_event_type`, `/event_types duplicate`, `/event_types too_many`, `/event_schema_versions unsupported_schema_version`, `/payload_mode invalid`, `/rate_limit_per_second out_of_range`, `/status invalid`.
422	`idempotency_key_reuse`	The `Idempotency-Key` was used with a different request.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks `webhook-endpoints:write`.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	Webhook administration is temporarily unavailable; retry after the `Retry-After` period.

Example

curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'

CLI: keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated