Register an HTTPS endpoint; the signing secret is returned once
POST/v1/webhooks
At most 10 endpoints per organization by default (your platform operator sets the limit); the next create answers 409 webhook_limit with details.limit. The signing secret is in this response only. This call takes no Idempotency-Key: if you lost the response, list your webhooks, find the endpoint and rotate its secret with expire_previous_now: true.
Access: API key scope webhooks:write on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 kb_not_in_allowlist); refused with 403 integrations_disabled while webhooks are switched off for the platform or your organization.
Request
Responses
- 201
- 403
- 409
- 422
Created. secret is shown only in this response.
scope_missing (details.required_scope), role_insufficient, kb_not_in_allowlist, integrations_disabled (details.area, details.scope), domain_blocked.
webhook_limit, secret_rotation_in_progress, domain_exists, redelivery_unavailable, idempotency_key_conflict, idempotency_in_progress.
validation_failed, webhook_url_rejected (details.rule), event_type_unknown, domain_invalid, method_not_allowed_for_domain.