Create webhook endpoint

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

beta_feature_not_enabled · 41002 · 403

The workspace needs private-beta access for calling APIs and explicit call-event subscriptions.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 403 · 41002

{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}

workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

account_not_found · 20020 · 404

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_webhook_already_exists · 40008 · 409

List the account’s independent endpoints using account_id and update the existing active endpoint. To switch, deactivate the old active endpoint before activating another. Do not automatically retry creation or reactivation.

What to do: Read the endpoint configuration and account scope before resubmitting. PATCH replaces settings; retain the intended subscriptions, signing configuration and retry policy. For an active-endpoint conflict, update the existing endpoint or deactivate it before enabling another.

Example · 409 · 40008

{
  "request_id": "req_example_webhook_conflict",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}

create_webhook_endpoint_failed · 40001 · 500

Create webhook endpoint: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the endpoint configuration and account scope before resubmitting. PATCH replaces settings; retain the intended subscriptions, signing configuration and retry policy. For an active-endpoint conflict, update the existing endpoint or deactivate it before enabling another.

Illustrative JSON; message varies with the actual cause · 500 · 40001

{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}